Upgrade on an offline 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.6 in order to upgrade to version 7.7. Patching, however, is possible in between any two 7.7 patches.

tip

It is highly recommended to backup your system before proceeding with an Axiomatics Services Manager (ASM) upgrade.

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.

Requirements

For the offline installation of ASM, you need to acquire the following files from Axiomatics:

• artifacts.zip
• axiomatics-services-manager-VERSION.zip
• registryData.zip
• registryImage.tar

Contact Axiomatics Customer SupportOpens in a new tab if you have not received them.

Important

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

1. Navigate to the existing ASM folder, 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

2. For upgrades only, remove the volume of the DB container.

   Important

   This step will erase all DB data and should be skipped when patching ASM. For upgrades, make sure you have backed up your data before proceeding.

   docker volume rm docker_db

3. If the old registry still exists, stop and delete it, and remove the volume.

   docker stop registry
   docker rm registry -v

4. Extract the contents of axiomatics-services-manager-<version>.zip to the folder where you want to run ASM on.

5. Navigate to the folder of the extracted distribution and restore the Docker Registry Image.

   docker load -i registryImage.tar

6. Unzip the Docker Registry Image Volume (registryData.zip).

7. Run the Registry Container.

   note

   Replace <ABSOLUTE_PATH_TO_DIR> with the path of the registry directory.

   docker run -d -p 5000:5000 --restart=always --name registry -v /<ABSOLUTE_PATH_TO_DIR>/registry:/var/lib/registry registry:2

8. Exctract artifacts.zip and copy the artifacts folder to the ASM docker folder.

9. Update the axiomatics-services-manager-<version>/docker/.env file with the following values:

   note

   The file may be hidden.

   CONNECTION=offline
   REGISTRY=localhost:5000/

10. 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.

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

    note

    This file is provided separately by Axiomatics.

12. Enable the BuildKit feature of Docker:

    Linux/macOS

    export DOCKER_BUILDKIT=1

    Windows

    Run the following command using PowerShell:

    Env:DOCKER_BUILDKIT=1

13. 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

14. Optionally, if you are using custom Attribute Connectors, restore the docker/asm.core/attribute.connectors/custom-attribute-connectors folder that you backed up previously.

15. Build the ASM image and start all the service's containers.

    Dashboard enabled

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

    Dashboard disabled

    docker-compose up --build

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