Upgrade on a Docker environment

The Axiomatics Services Manager (ASM) upgrading process can only be performed between two consecutive minor versions, meaning that you must be running version 7.4 in order to upgrade to version 7.5.

However, patching is possible between any two 7.5 patches.

Important

It is essential to backup your system before proceeding with an Axiomatics Services Manager (ASM) upgrade due to a major PostgreSQL update. Otherwise, your data will be lost.

note

Upgrading or patching ASM will cause downtime for the application and consequently a temporary loss of service. As a result, the upgrade should be planned accordingly.

Important

When upgrading the logs won't be migrated. The old logs directory will still contain the previous logs.

1. Navigate to the docker folder of the existing ASM deployment.

2. Stop ASM and remove all the containers.

   Dashboard enabled

   The Dashboard provides visualization of key metrics for monitoring the authorization performance of the running instances of Access Decision Service (ADS).

   docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml down

   Dashboard disabled

   docker-compose down

3. Unzip the ASM 7.5 distribution to the folder where you want to run ASM on.

4. Navigate to the docker folder of the extracted distribution and open credentials.txt using a text editor.

   Update the placeholder values for Access key ID and Secret access key with the values provided by Axiomatics.

   tip

   These are the same values that were used when AWS CLI was configured.

5. Optionally, you can run ASM on a machine with a hostname other than the default as follows:

   Change the default hostname

   1. Navigate to the docker folder of the extracted distribution.
   2. Update the HOST variable in the .env file. The default value is localhost.
   3. Save the file and exit.

6. Copy a valid ASM license file to the docker folder.

   note

   This file is provided separately by Axiomatics.

7. Enable the BuildKit feature of Docker:

   Linux/macOS

   export DOCKER_BUILDKIT=1

   Windows

   Run the following command using PowerShell:

   $Env:DOCKER_BUILDKIT=1

8. Configure the SSL Certificate common name.

   In production environments, you should import trusted certificates only, while in dev and test environments you have the ability to create a self-signed certificate.

   Import

   ASM requires a PKCS#12 (Public Key Cryptography Standard #12) certificate. In case you already have a certificate with different format such as .pem, you should convert it to PKCS#12. The certificate file must be named cert.keystore.p12. During the creation of the certificate, the name (or alias) must be set to server.

   1. Navigate to the docker/api.gateway/certs/ folder of the extracted distribution.
   2. Copy your certificate to this folder.

   Create

   Generate a self-signed certificate as follows:

   1. Navigate to the docker folder of the extracted distribution.

   2. Open the .env file and update the following entries:

      • CERTIFICATE_CN with your common name
      • CERTIFICATE_KEY_STORE_PASSWORD with your password

   3. Generate the certificate:

      Linux/macOS

      1. From the docker/api.gateway/certs/ folder, run the following command.

         sh generate_self_signed_certificate.sh

      2. Make sure that the following files were created:

         • cert.keystore.p12
         • server.crt

      Windows

      1. From the docker\api.gateway\certs folder, run the following commands using PowerShell.

         Important

         In the first command, replace <your_cert_key_store_pw> and <your_cert_cn> with the same values that were previously used in the .env file.

         docker build -t certificate -f ./Dockerfile.cert . --build-arg CERTIFICATE_KEY_STORE_PASSWORD=<your_cert_key_store_pw> --build-arg CERTIFICATE_CN=<your_cert_cn>

         docker create --name cert certificate; docker cp cert:/cert.keystore.p12 ./cert.keystore.p12; docker cp cert:/server.crt ./server.crt; docker rm -f cert; docker image rm certificate

      2. Make sure that the following files were created:

         • cert.keystore.p12
         • server.crt

9. Optionally, if you are using custom Attribute Connectors, restore the docker/asm.core/attribute.connectors/custom-attribute-connectors folder from the previous ASM deployment.

10. Start all the service's containers again.

    Dashboard enabled

    docker-compose -f docker-compose.yml -f docker-compose.dashboard.yml up --build

    Dashboard disabled

    docker-compose up --build

11. If you are upgrading ASM, restore your backed up data.