Upgrade

Daria Barysheva, Adelya Zvyagintseva

Contents

Upgrade using ADCM Installer
Online upgrade
Offline upgrade

CAUTION

General recommendations and limitations

Before upgrading, it is strongly recommended to back up ADCM data. For more information, see Backup and restore.
Downgrade of the ADCM version is not supported.
It is not recommended to update ADCM more than 5 minor versions ahead (see <minor> in the versioning format below).
Before upgrading ADCM to version 2.7.0, migrate data from SQLite to PostgreSQL. Migration can be performed in any ADCM version up to and including 2.6.0.

Version restrictions during upgrade

Version 2.10.0 is mandatory for installation and cannot be skipped. Direct upgrade from versions lower than 2.10.0 to 2.11.0 and later is not supported.
If installed clusters contain products with an outdated contract version, a warning about unsupported contract versions is displayed in the Docker container logs.
If installed clusters contain products with an unsupported contract version, the Docker container startup is stopped. Such products should be updated to a supported version.

IMPORTANT

ADCM 3.0.0 is required for installation and cannot be skipped during the upgrade.

Starting with ADCM 3.0.0, all processes inside the Docker container run as the unprivileged adcm user (UID/GID 10001) instead of the root user.

When upgrading without using ADCM Installer from an ADCM version earlier than 3.0.0, change the ownership of the /adcm/data directory before starting the container with the new ADCM version for the first time. Otherwise, the Docker container will not be able to access the existing data and will terminate.

If data is stored in a Docker volume, perform the following steps:

Determine the name of the Docker volume mounted at the /adcm/data directory:
```
$ sudo docker inspect \
    --format='{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}{{"\n"}}{{end}}{{end}}' \
    adcm
```
The command returns the name of the Docker volume. Use this name instead of <volume_name> in the next command.

Change the ownership of the data directory:

$ sudo docker run --rm \
    -v <volume_name>:/adcm/data \
    --user 0:0 \
    --entrypoint sh \
    hub.arenadata.io/adcm/adcm:<version> \
    -c 'chown -R 10001:10001 /adcm/data'

where <version> is the ADCM version to which you want to upgrade.

The ADCM update process depends on the installation method of ADCM.

Upgrade using ADCM Installer

If ADCM was deployed using ADCM Installer, the update is performed by modifying the configuration and applying the changes using the adi utility.

To update ADCM to the required version, follow these steps:

Open the adcm.yaml configuration file used during installation. The configuration file example is provided in the Use ADCM Installer article.
In the section corresponding to ADCM, specify the Docker image of ADCM with the required version tag in the image parameter, for example, hub.arenadata.io/adcm/adcm:2.12.0.
Apply the changes:
```
$ sudo adi apply
```
After the command is executed, the ADCM container will be recreated using the image specified in the image parameter of the adcm.yaml file.

Online upgrade

If you need to upgrade the previously installed version of ADCM that was installed without using ADCM Installer, do the following:

Stop and remove the adcm container:
```
$ sudo docker rm -f adcm
```

Download the required Docker image from the Arenadata Docker Registry:

$ sudo docker pull hub.arenadata.io/adcm/adcm:<version>

where <version> is the desired ADCM image version in one of the following formats:

<major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.
<major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

IMPORTANT

latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.
Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

Create and start a new Docker container based on the downloaded image, choosing the option depending on how the previous ADCM version was installed:

IMPORTANT

When upgrading ADCM, use the same data storage method (bind mount or named volume) as in the previous installation. Changing the storage method without prior backup and restore will cause data loss.

If a named volume was previously used:

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

If a bind mount was previously used:

NOTE

Before starting the container, make sure that the existing data directory is owned by 10001:10001. If necessary, change the owner:

$ sudo chown -R 10001:10001 /opt/adcm

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

NOTE

For more information on the environment variables (DB_HOST, DB_PORT, DB_USER, DB_NAME, DB_PASS, and DB_OPTIONS), see the Installation article.

Offline upgrade

You can also try offline ADCM update in situations without Internet access.

To upgrade ADCM that was installed without using ADCM Installer offline, follow these steps:

Stop and remove the adcm container:

$ sudo docker rm -f adcm

NOTE

For customers who use Enterprise editions of products, it is possible to contact the Arenadata support team to get an archive with the sh.xz extension that contains a special installation shell script. After stopping the adcm container, the ADCM update process includes the installation according to the instruction.

Download the required Docker image from the Arenadata Docker Registry on a host that has Internet access:

$ sudo docker pull hub.arenadata.io/adcm/adcm:<version>

where <version> is the desired ADCM image version in one of the following formats:

<major>.<minor>.<patch> — if you need a specific ADCM patch. For example, 2.0.0.
<major>.<minor> — if you need the last patch within the selected ADCM version. For example, 2.0.

IMPORTANT

latest was used for earlier versions of ADCM and is no longer supported starting from version 2.0.0.
Before ADCM 2.0.0, the following format was used for versioning: YYYY.MM.DD.HH.

Save the Docker image to a .tar file:
```
$ sudo docker save -o <file_name> hub.arenadata.io/adcm/adcm:<version>
```
where <file_name> is the full name of the created file with the extension (for example, adcm_2.5.0_arenadata.tar).

NOTE
Running the command can take some time. Please wait until it is completed.
Copy the saved file from the current host to a host without Internet connection using any available methods.

IMPORTANT
Make sure you have configured access to hosts and necessary file permissions.
Load the Docker image from the .tar file:
```
$ sudo docker load -i <file_path>
```
where <file_path> is the absolute path to the .tar file with the Docker image.

The example of a successful command execution result:
```
Loaded image: hub.arenadata.io/adcm/adcm:2.5.0
```

Create and start a new Docker container based on the downloaded image, choosing the option depending on how the previous ADCM version was installed:

IMPORTANT

When upgrading ADCM, use the same data storage method (bind mount or named volume) as in the previous installation. Changing the storage method without prior backup and restore will cause data loss.

If a named volume was previously used:

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v adcm-data:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

If a bind mount was previously used:

NOTE

Before starting the container, make sure that the existing data directory is owned by 10001:10001. If necessary, change the owner:

$ sudo chown -R 10001:10001 /opt/adcm

$ sudo docker run \
    --name adcm \
    -p 8000:8000 \
    -v /opt/adcm:/adcm/data \
    -e DB_HOST="<DATABASE_HOSTNAME_OR_IP_ADDRESS>" \
    -e DB_PORT="<DATABASE_TCP_PORT>" \
    -e DB_USER="<DATABASE_USERNAME>" \
    -e DB_NAME="<DATABASE_NAME>" \
    -e DB_PASS="<DATABASE_USER_PASSWORD>" \
    -e DB_OPTIONS="<DATABASE_OPTIONS>" \
    hub.arenadata.io/adcm/adcm:<version>

NOTE

For more information on the environment variables (DB_HOST, DB_PORT, DB_USER, DB_NAME, DB_PASS, and DB_OPTIONS), see the Installation article.

Found a mistake? Seleсt text and press Ctrl+Enter to report it