Application manifest

An application manifest defines the various attributes of an application.

The available attributes are listed in the following table:

Image

The image attribute defines which image the application is based on. If left empty, your application is based on the default image. See How to manage images for more details on this. Available images on your installation can be listed with the following command:

amc image list

Node selector

The node-selector attribute allows specifying a list of selectors to limit the LXD nodes on which a container for the application can be scheduled. AMS will match the selector against the tags specified for each node.

The following manifest specifies a node selector that instructs the AMS to schedule only those containers having the tags foo and bar, onto a node:

name: candy
instance-type: a4.3
node-selector: [foo, bar]

Video encoder

A video encoder type can be specified through the video-encoder field in the manifest file when creating an application, so that a container launched from the application can use a GPU or software video encoder according to different scenarios.

When gpu video encoder is specified in the manifest, AMS can fail to create an application if:

• All GPU slots are used up by running containers.
• There is no GPU support across the entire LXD cluster.

Watchdog settings

The watchdog attribute includes the following field definitions:

When a container is launched, Anbox enables an application watchdog by default for the installed package unless it’s disabled explicitly with:

name: candy
instance-type: a4.3
image: default
watchdog:
  disabled: true

If one of the following scenarios occurs, the watchdog will be triggered. The container will be terminated and ends up with error status.

• The application crashes or an ANR is triggered.
• The application is not in the foreground when an application which is not listed in allowed-packages was brought to the foreground and gained the focus.
• The boot package or activity is invalid.
• One of the allowed-packages is invalid.

The rules forbid launching another activity, not part of the installed package or listed allowed packages. Launching activities of the same package is allowed.

Supplying ['*'] to the allowed-packages when the watchdog is enabled allows any application to be displayed in the foreground without triggering a watchdog.

Services

A container launched from the installed application can expose services you want to make accessible from outside the container. You must define the following properties for each service:

Resources

If the instance-type that is provided by AMS doesn’t meet the criteria that the installed application requires to function, you can use the resources directive to override the predefined resources.

In the following application manifest file, the application is created with a4.3 instance type, which will be assigned 4 vCPU cores, 3 GB of memory and a disk size of 3 GB. With the following resources defined in the manifest file, the allocated memory and disk size will end up at 4 GB and 8 GB, respectively, on application installation, and the number of vCPU cores remains the same:

name: candy
instance-type: a4.3
resources:
  memory: 4GB
  disk-size: 8GB

If all required fields (cpus/memory/disk-size) of resources are supplied in the application manifest, the instance-type field is no longer needed. Even if the instance-type field is provided, it will be overridden by the requirements in the resources fields upon application installation.

Extra data

Some Android applications which contain large program assets such as graphics or media files use so-called OBB files to store additional data. These data files are separated from the APK and saved onto the external or internal SD card of an Android device. The extra-data field can be used in this case to install an APK with separated OBB files or any other additional data into the Android system.

Each item of extra-data should be declared as follows:

<name>:
    target: <target-path>
    owner:  <uid>:<gid> # optional
    permissions: <file-permission> # optional

The fields have the following purpose:

permissions represents Linux file permissions in octal notation.

It’s recommended to let Anbox choose the right values for owner and permissions instead of manually providing them. If owner and permissions are not specified, the following default values will be used:

Each item (file or folder) declared in the extra-data field of the manifest YAML file should be placed in a directory called extra-data.

For security reasons, the target location of the files and directories listed in the extra-data section is restricted to a few specific locations in the Android file system. These are:

• /sdcard/Android/obb/<apk-package-name>
• /sdcard/Android/data/<apk-package-name>
• /data/app/<apk-package-name>
• /data/data/<apk-package-name>

The manifest and extra data in our example are placed next to the application package, which must be named app.apk:

.
├── app.apk
├── extra-data
│   ├── com.canonical.candy.obb
│   └── game-data-folder
│       └── data.bin
└── manifest.yaml

Hooks

Hooks allow you to run custom scripts when a certain event is triggered in a container life cycle. See Hooks for more details about the usage of hooks in an application.

Bootstrap

An application bootstrap can be fine-tuned through the bootstrap field.

The bootstrap attribute includes the following field definitions:

To minimise the application size, most contents under the APP_DIR directory are removed when the application bootstrap is finished. By default, only the metadata content is preserved (the manifest.yaml file and the hooks directory, if present). If a hook requires any other files under the APP_DIR directory during the regular container runtime, you must include them in the application image.

name: my-application
instance-type: a4.3
bootstrap:
  keep:
    - 'apks/*.apk'
    - 'scripts'

This will include the scripts folder and all APK files under the apks folder in the application image when the bootstrap is done, so that they are available to use during the regular container runtime.

Last updated a month ago.