How to update an application

Updating an existing application works similar to creating a new one. Each time an existing application is updated, it is extended with a new version. All versions that an application currently has are individually usable, but only one can be launched at a time.

When you want to update an existing application with a new manifest or APK, provide both in the same format as when the application was created. The amc application update command accepts both a directory and an absolute file path.

From a path:

amc application update bcmap7u5nof07arqa2ag $PWD/foo

From a file:

amc application update bcmap7u5nof07arqa2ag foo.tar.bz2

AMS will start the update process internally. You can watch the status of the new version with the following command:

amc application show bcmap7u5nof07arqa2ag

The output shows detailed information about the application and all of its versions:

id: bcmap7u5nof07arqa2ag
name: candy
status: ready
published: false
config:
  instance-type: a4.3
  boot-package: com.canonical.candy
versions:
  0:
    image: bf7u4cqkv5sg5jd5b2k0 (version 0)
    published: false
    status: active
    addons:
    - ssh
    boot-activity: com.canonical.candy.GameApp
    required-permissions:
    - android.permission.WRITE_EXTERNAL_STORAGE
    - android.permission.READ_EXTERNAL_STORAGE
    extra-data:
      com.canonical.candy.obb:
        target: /data/app/com.canonical.candy-1/lib
      game-data-folder:
        target: /sdcard/Android/data/com.canonical.candy/
    watchdog:
      disabled: false
      allowed-packages:
      - com.android.settings
    services:
    - port: 5559
      protocols:
      - tcp
      expose: false
      name: adb
  1:
    image: bf7u4cqkv5sg5jd5b2k0 (version 0)
    published: false
    status: active
    addons:
    - ssh
    boot-activity: com.canonical.candy.GameApp
    required-permissions:
    - android.permission.READ_EXTERNAL_STORAGE
    - android.permission.READ_EXTERNAL_STORAGE
    extra-data:
      com.canonical.candy.obb:
        target: /data/app/com.canonical.candy-1/lib
    watchdog:
      disabled: false
      allowed-packages:
      - com.android.settings
    services:
    - port: 5559
      protocols:
      - tcp
      expose: false
      name: adb
resources:
  cpus: 4
  memory: 4GB
  disk-size: 8GB

Each version gets a monotonically increasing number assigned (here we have version 0 and version 1). In addition, each version has a status which indicates the status of the bootstrap process AMS is performing for it. Once an application version is marked as active, it is ready to be used.

Publish application versions

The most important part of an application version is the published field. If a version is marked as published, it is available to launch and use. Generally when launching instances by using the AMS REST API, if no specific application version is given, by default, the latest published version of an application is used to create the instance.

If application.auto_publish (in AMS configuration) is set to true (the default), new versions are automatically published. Otherwise, you need to publish them manually.

You can mark an application version as published with the following command:

amc application publish bcmap7u5nof07arqa2ag 1

To revoke an application version, use the following command:

amc application revoke bcmap7u5nof07arqa2ag 1

If an application has only a single published version and that version is revoked, the application can’t be used by any users anymore. AMS will still list the application but will mark it as not published as it has no published versions.

Delete application versions

Each version takes up space on the LXD nodes. To free up space and remove old and unneeded versions, you can individually remove them, with the only requirement that an application must have at least a single version at all times. Removing a specific application version is possible with the following command:

amc application delete --version=1 bcmap7u5nof07arqa2ag

The command will ask for your approval before the version is removed as it might affect your users. If you want to bypass the check, you can add the --yes flag to the command.

Configure automatic updates

AMS automatically updates an application whenever any of its dependencies (parent image, addons, global configuration) changes. This produces a new version for the application, which is automatically published if the application.auto_publish configuration item is enabled.

In some cases, an automatic update is not wanted. To support this, AMS allows disabling automatic application updates via the application.auto_update configuration update.

To disable automatic updates:

amc config set application.auto_update false

To enable automatic updates:

amc config set application.auto_update true

When automatic updates are disabled, applications must be manually updated for any changed dependencies. To do this, use the following command:

amc application update <application id or name>

This will initiate the update process and create a new application version.

Change base image

The image an application is based on can be changed with the following command:

amc application set com.canonical.candy image <image name or id>

Changing the image will cause AMS to generate a new version for the application. Previous versions will continue using the image the application used before.