Application manifest¶
An application manifest defines the various attributes of an application.
The available attributes are listed in the following table:
Name |
Value type |
Description |
Status |
---|---|---|---|
|
string |
Verbose name of the application. The following special characters are not allowed: |
Supported |
|
string |
Version to encode with the application. Maximum length is 50 characters. |
Supported |
|
string |
Instance type that all instances created for the application will use. Learn more |
Deprecated since 1.20 |
|
array of strings |
List of permissions to automatically grant to the application. See Android Permissions for a list of available permissions. If |
Supported |
|
string |
Name or ID of an image to be used for the application. The default image is used if empty. Learn more |
Supported |
|
array |
List of addons to be installed during the application bootstrap process. |
Supported |
|
array |
List of tags to be associated with the application. |
Supported |
|
string |
Package to launch once the system has booted (default: package name retrieved from the APK if APK file is present). |
Supported on AOSP only |
|
string |
Activity of boot package to launch once the system has booted (default: main activity as defined in the application manifest). |
Supported on AOSP only |
|
string |
Video encoder to be used by an instance launched from the application (default: |
Supported |
|
map |
Watchdog settings to be configured on application installation. Learn more |
Supported |
|
array |
Services to be provided from the installed application. Learn more |
Supported |
|
map |
Resources to be allocated on application installation. Learn more |
Supported |
|
array |
List of additional data to be installed on application installation. Learn more |
Supported |
|
object |
Hooks settings to be configured on application installation. Learn more |
Supported |
|
object |
Application bootstrap settings to be configured on application installation. Learn more |
Supported |
|
array |
List of feature flags to be defined for instances created from the application. |
Supported |
|
array |
List of selectors which will limit what node an instance for the application can be scheduled on. Learn more |
Supported |
Instance type¶
Note
The instance-type
attribute is deprecated since 1.20. For any application, a default set of resources will be chosen. If you wish to set specific resources to your application, use the resources
attribute to do so.
When using the web dashboard to create an application, the field Instance type is changed to Resource type to maintain backward compatibility.
Similar to other clouds, Anbox Cloud describes the amount of resources that are available to a single instance with an instance type. An instance type is a name that is mapped to a set of resources. This allows to have an easy abstraction when referring to resource requirements of instances or particular applications.
Anbox Cloud offers the following instance types:
Name |
vCPU cores |
RAM |
Disk size |
GPU slots |
---|---|---|---|---|
a2.3 |
2 |
3 GB |
3 GB |
0 |
a4.3 |
4 |
3 GB |
3 GB |
0 |
a6.3 |
6 |
3 GB |
3 GB |
0 |
a8.3 |
8 |
3 GB |
3 GB |
0 |
a10.3 |
10 |
3 GB |
3 GB |
0 |
g2.3 |
2 |
3 GB |
3 GB |
1 |
g4.3 |
4 |
3 GB |
3 GB |
1 |
g6.3 |
6 |
3 GB |
3 GB |
1 |
g8.3 |
8 |
3 GB |
3 GB |
1 |
g10.3 |
10 |
3 GB |
3 GB |
1 |
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 Anbox Cloud 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 an instance for the application can be scheduled. AMS will match the selector against the tags specified for each node. See Tags for more information.
The following manifest specifies a node selector that instructs the AMS to schedule only those instances having the tags foo
and bar
, onto a node:
name: candy
resources:
cpus: 4
memory: 3GB
disk-size: 3GB
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 an instance launched from the application can use a GPU or software video encoder according to different scenarios. Virtual machines do not have GPU support and hence will use software video encoding.
Name |
Description |
---|---|
|
A GPU-based video encoder |
|
A GPU-based video encoder if GPU slots are not used up, otherwise, fall back to use a software-based video encoder |
|
A software-based video encoder |
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 instances.
There is no GPU support across the entire LXD cluster.
Watchdog¶
The watchdog
attribute includes the following field definitions:
Name |
Value type |
Description |
---|---|---|
|
Boolean |
Toggle application watchdog on or off (default: false) |
|
array of strings |
Besides the boot package, list of packages to be allowed to display in the foreground |
When an instance is launched, Anbox enables an application watchdog by default for the installed package unless it’s disabled explicitly with:
name: candy
image: default
resources:
cpus: 4
memory: 3GB
disk-size: 3GB
watchdog:
disabled: true
If one of the following scenarios occurs, the watchdog will be triggered. The instance 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¶
An instance launched from the installed application can expose services
you want to make accessible from outside the instance. You must define the following properties for each service:
Name |
Value type |
Description |
---|---|---|
|
string |
Name of service |
|
integer |
Port number to be exposed by the service |
|
array of strings |
Protocols to be used by the service (Possible values are: |
|
Boolean |
Expose service to be accessible externally or internally |
Resources¶
The resources
directive helps you define the required resources for your application.
Name |
Value type |
Minimum value |
Description |
---|---|---|---|
|
integer |
1 |
Number of vCPU cores |
|
string |
3 GB |
Memory to be assigned to the application |
|
string |
3 GB |
Disk size to be assigned to the application |
|
integer |
0 |
Number of GPU slots to be assigned to the application |
Note that if all required fields (cpus
/memory
/disk-size
) of resources
are supplied in the application manifest and the deprecated instance-type
field is also provided, instance-type
will be overridden by the requirements in the resources
fields upon application installation.
See Resources and resource presets for more information.
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:
Name |
Value type |
Description |
---|---|---|
|
string |
Name of file or directory to be installed into the Android file system |
|
string |
Target location for the file or directory |
|
string |
Owner assigned to the target file or directory in the Android file system |
|
string |
Permissions assigned to the target file or directory in the Android file system |
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:
Name |
App data installation directory |
Type |
Value |
---|---|---|---|
|
SD card |
File |
|
SD card |
Dir |
|
|
system data |
File |
|
|
system data |
Dir |
|
|
|
SD card |
File |
0660 |
SD card |
Dir |
0771 |
|
system data |
File |
0660 |
|
system data |
Dir |
boot package folder -> 0700, nested folders of boot package folder -> 0770 |
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 the life cycle of an instance. 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:
Name |
Value type |
Description |
---|---|---|
|
array |
Contents under the APP_DIR directory to be preserved in the application image after the bootstrap is finished. Wildcard patterns are supported. See Environment variables and pattern syntax for more information. |
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. If a hook requires any other files under the APP_DIR
directory during the regular instance runtime, you must include them in the application image.
name: my-application
resources:
cpus: 4
memory: 3GB
disk-size: 3GB
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 instance runtime.
Because it contains metadata, the manifest.yaml
file and the hooks
directory (if present) are not removed when the application bootstrap is finished and are always kept in the application image even if they are not explicitly defined in the keep
list under the bootstrap
attribute.