Appliance Update Guide

We recommend that you update your Anapaya appliance in a timely manner to stay current with the latest enhancements and fixes. This guide provides a general step-by-step procedure to update your Anapaya appliance with the Anapaya appliance installer. For a more extensive explanation of the update procedure, refer to the Appliance Software Updates documentation. Upgrading between minor versions is generally safe, and automatic rollback in case of failure is supported.

Note

Make sure to consult the version specific release and upgrade notes referenced on the Release Notes page. They will mention known issues that potentially might affect your upgrade, or additional steps that need to be taken during an upgrade.

Prerequisites

Access to software packages

To download the software packages, you require an access token that is provided as part of your software license. If you do not have access to that token, consult with your Anapaya Customer Sucess Engineer.

Access to appliance API

To access the appliance API you need to know the configured API address and a set of credentials to authenticate to the appliance. Further you need to have network connectivity to the appliance such that you can reach it at the configured address. If you perform the update form a shell on the appliance itself, it is the localhost address 127.0.0.1.

Note

In the case where you perform the upgrade form a shell on the appliance itself where the host has no internet access, the keys, the signatures and the packages need to be downloaded on a host with internet access and copied to the appliance.

Credentials

In case authentication was configured on the appliance, credentials need to be specified when interacting with the management API by extending the curl command with the -u <username>:<password> argument.

curl -u <username>:<password> <url>
Up-to-date public keys

Ensure that the set of public key used for code verification is up-to-date with the currently published set on https://releases.anapaya.net/keys.json

curl https://releases.anapaya.net/keys.json > reference_keys.json
curl -k https://$APPLIANCE_API/api/v1/software/keys > keys.json
# or
appliance-cli get software/keys > keys.json
diff <(jq --sort-keys . reference_keys.json) <(jq --sort-keys . keys.json)

If the keys differ please follow instructions in the Updating installed public keys section to update them.

Update the anapaya-scion package

To update the anapaya-scion package, first download the package its signature then upload both files to the appliance and finally trigger the installation.

Note

In the following commands, the variables ($VERSION_SCION, $VERSION_SYSTEM, $APPLIANCE_API, $ACCESS_TOKEN) must be replaced with the actual values.

We recommend setting the variables as environment variables

export APPLIANCE_API=Z.Z.Z.Z
export VERSION_SCION=v0.XX.Y
export VERSION_SYSTEM=vA.B.C

or replace the variables directly in the commands.

By providing the values here, the commands are automatically updated with the correct values.

Version anapaya-scion:   Version anapaya-system:   Appliance API Address:

  1. Download the anapaya-scion package of the desired version from cloudsmith.io

    wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-scion/versions/$VERSION_SCION_PH/anapaya-scion-$VERSION_SCION_PH.tar.gz

  2. Download the anapaya-scion package signature from the Anapaya website

    curl https://releases.anapaya.net/anapaya-scion-$VERSION_SCION_PH.tar.gz.signatures.json > signatures.json

  3. Upload the package signatures to the appliance installer

    appliance-cli post software/signatures/scion/$VERSION_SCION_PH <signatures.json
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/signatures/scion/$VERSION_SCION_PH -X POST -d @signatures.json

  4. Upload the package to the appliance installer

    appliance-cli post software/scion/packages/local <anapaya-scion-$VERSION_SCION_PH.tar.gz
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/scion/packages/local -X POST --data-binary "@anapaya-scion-$VERSION_SCION_PH.tar.gz"

  5. Trigger the installation

    appliance-cli post software/scion/install 'version: $VERSION_SCION_PH'
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/scion/install -X POST -d '{"version": "'"$VERSION_SCION_PH"'"}'

    Note

    In case of a failed installation of an anapaya-scion package, a rollback to the original version is triggered automatically and no interaction is required.

    Tip

    You can check the installation progress by running the following command:

    watch appliance-cli get software/scion/install/$ID
# or
watch curl -k https://$APPLIANCE_API_PH/api/v1/software/scion/install/$ID

    The $ID corresponds to the installation identifier of the installation that you have triggered. You will find it in the output of the triggered installation.

  6. Finally, check if the installation has completed and the new version is installed.

    appliance-cli get software/scion/installed
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/scion/installed

Rollback was triggered

When a rollback is triggered due to a failed installation of the new version, investigate the reason by looking at the logs of the installer:

journalctl -u appliance-installer.service

Note

Sometimes, the installation of a package fails due to a lock that cannot be acquired by the installer. In that case, a rollback is triggered. To verify that the rollback was triggered because of this known issue, you can check the installer logs for the following error:

Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend)

If that is the case, an installation can just be retried.

Update the anapaya-system package

Updating an anapaya-system package is analogous to the process for the anapaya-scion package, with the difference that no rollbacks are supported.

To update the anapaya-systems package, first download the package its signature then upload both files to the appliance and finally trigger the installation.

  1. Download the anapaya-system package of the desired version from cloudsmith.io

    wget https://dl.cloudsmith.io/$ACCESS_TOKEN/anapaya/stable/raw/names/anapaya-system/versions/$VERSION_SYS_PH/anapaya-system-$VERSION_SYS_PH.tar.gz

  2. Download the anapaya-system package signature from the Anapaya website

    curl https://releases.anapaya.net/anapaya-system-$VERSION_SYS_PH.tar.gz.signatures.json > signatures.json

  3. Upload the package signatures to the appliance installer

    curl -k https://$APPLIANCE_API_PH/api/v1/software/signatures/system/$VERSION_SYS_PH -X POST -d @signatures.json

  4. Upload the package

    curl -k https://$APPLIANCE_API_PH/api/v1/software/system/packages/local -X POST --data-binary "@anapaya-system-$VERSION_SYS_PH.tar.gz"

  5. Trigger the installation

    appliance-cli post software/system/install 'version: $VERSION_SYS_PH'
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/system/install -X POST -d '{"version": "'"$VERSION_SYS_PH"'"}'

  6. Finally, check if the installation has completed and the new version is installed.

    appliance-cli get software/system/installed
# or
curl -k https://$APPLIANCE_API_PH/api/v1/software/system/installed