Upgrade Autonomous Identity

Autonomous Identity provides an upgrade command to update your core software to the latest version while migrating your data.

Upgrade Considerations

  • Database Systems are the Same. If your current database is Apache Cassandra, you cannot upgrade to a MongoDB-based system. You will need to run a clean installation with the new version.

  • Host IPs should be the Same. Host IP addresses must be the same for existing components. You must update the ~/autoid-config/hosts file by adding the IP addresses for the Elasticsearch entries. See the instructions below.

  • Registry Key Required. To download the deployment images for the upgrade, you still need your registry key to log into the ForgeRock Google Cloud Registry (gcr.io). Copy your registry key from your previous build to your new upgrade.

Make sure to test the upgrade on a staging or QA server before running it in production.

Upgrade Paths

The upgrade assumes the following upgrade paths depends on your current deployment version. The preferred upgrade path is to the latest patch release. The following chart summarizes these upgrade paths:

Table 1: Upgrade Paths
Version Upgrade To See

2021.8.x (2021.8.0–2021.8.2)

2021.8.3

2021.8.x (2021.8.0–2021.8.2) Air-Gapped

2021.8.3 Air-Gapped

2021.3.x (2021.3.0–2021.3.5)

2021.3.0–2021.3.4 → 2021.3.5 → 2021.8.0 → 2021.8.3

Upgrade from Autonomous Identity 2021.8.0 to 2021.8.3

The following instructions are for upgrading from Autonomous Identity version 2021.8.x (2021.8.0, 2021.8.1, 2021.8.2) to the latest version 2021.8.3 in non air-gapped deployments.

Upgrade from 2021.8.x to 2021.8.3 Non Air-Gap:

  1. On the deployer machine, back up the 2021.8.x ~/autoid-config directory or move it to another location.

    $ mv ~/autoid-config ~/backup-2021.8.x
  2. Create a new ~/autoid-config directory.

    $ mkdir ~/autoid-config
  3. Copy your autoid_registry_key.json, ansible.cfg, and vault.yml files from your backup directory to ~/autoid-config. If your vault.yml file is encrypted, copy the .autoid_vault_password file to ~/autoid-config.

  4. Copy your original SSH key into the new directory.

    $ cp ~/.ssh/id_rsa ~/autoid-config
  5. Change the permission on the SSH key.

    $ chmod 400 ~/autoid-config/id_rsa
  6. Check if you can successfully SSH to the target server.

    $ ssh autoid@<Target-IP-Address>
    
    Last login: Wed Dec 15 18:19:14 2021
  7. Stop the stack.

    If you are upgrading a multi-node deployment, run this command on the Docker Manager node.
    $ docker stack rm configuration-service consul-server consul-client nginx jas swagger-ui ui api notebook

    You should see:

    Removing service configuration-service_configuration-service
    Removing service consul-server_consul-server
    Removing service consul-client_consul-client
    Removing service nginx_nginx
    Removing service jas_jasnode
    Removing service swagger-ui_swagger-ui
    Removing service ui_zoran-ui
    Removing service api_zoran-api
    Nothing found in stack: notebook
  8. For multinode deployments, run the following on the Docker Worker node:

    $ docker swarm leave
  9. Enter exit to end your SSH session.

  10. From the deployer, restart Docker command:

    $ sudo systemctl restart docker
  11. On the deployer node, change to the ~/autoid-config directory.

    $ cd ~/autoid-config
  12. Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.

    $ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid

    You should see:

    Login Succeeded
  13. Run the create-template command to generate the deployer.sh script wrapper and configuration files. Note that the command sets the configuration directory on the target node to /config. The --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files.

    $ docker run --user=$(id -u) -v ~/autoid-config:/config \
    -it gcr.io/forgerock-autoid/deployer:2021.8.3 create-template
  1. Configure your upgraded system by editing the ~/autoid-config/vars.yml , ~/autoid-config/hosts , and ~/autoid-config/vault.yml files on the deployer machine.

    You must keep your configuration settings consistent from one system to another.
  2. Download the images. This step downloads software dependencies needed for the deployment and places them in the autoid-packages directory. Make sure you are in the ~/autoid-config directory.

    $ ./deployer.sh download-images
  3. Run the upgrade.

    1. If you are upgrading from version 2021.8.0, run the following:

      $ ./deployer.sh debug upgrade_2020_8
      
      $ docker stack rm configuration-service consul-server consul-client nginx jas swagger-ui ui api notebook
      
      $ ./deployer.sh debug patch_log4j
    2. If you are upgrading from version 2021.8.1 or 2021.8.2, run the following:

      $ ./deployer.sh debug patch_log4j
  4. Log out and then log back in to Autonomous Identity.

You have successfully upgraded your Autonomous Identity server to 2021.8.3.

Upgrade from Autonomous Identity 2021.8.x to 2021.8.3 Air-Gapped

The following instructions are for upgrading from Autonomous Identity version 2021.8.x (2021.8.0, 2021.8.1, 2021.8.2) to 2021.8.3 on air-gapped deployments.

Upgrade from 2021.8.x to 2021.8.3 Air-Gapped:

  1. On the deployer machine, back up the 2021.8.x ~/autoid-config directory or move it to another location.

    $ mv ~/autoid-config ~/backup-2021.8.x
  2. Create a new ~/autoid-config directory.

    $ mkdir ~/autoid-config
  3. Copy your autoid_registry_key.json, ansible.cfg, and vault.yml files from your backup directory to ~/autoid-config. If your vault.yml file is encrypted, copy the .autoid_vault_password file to ~/autoid-config.

  4. Copy your original SSH key into the new directory.

    $ cp ~/.ssh/id_rsa ~/autoid-config
  5. Change the permission on the SSH key.

    $ chmod 400 ~/autoid-config/id_rsa
  6. Stop the stack.

    If you are upgrading a multi-node deployment, run this command on the Docker Manager node.
    $ docker stack rm configuration-service consul-server consul-client nginx jas swagger-ui ui api notebook

    You should see:

    Removing service configuration-service_configuration-service
    Removing service consul-server_consul-server
    Removing service consul-client_consul-client
    Removing service nginx_nginx
    Removing service jas_jasnode
    Removing service swagger-ui_swagger-ui
    Removing service ui_zoran-ui
    Removing service api_zoran-api
    Nothing found in stack: notebook
  7. For multinode deployments, run the following on the Docker Worker node:

    $ docker swarm leave
  8. From the deployer, restart Docker:

    $ sudo systemctl restart docker
  9. On the deployer node, change to the ~/autoid-config directory.

    $ cd ~/autoid-config
  10. Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.

    $ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid

    You should see:

    Login Succeeded
  11. Run the create-template command to generate the deployer.sh script wrapper and configuration files. Note that the command sets the configuration directory on the target node to /config. The --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files.

    $ docker run --user=$(id -u) -v ~/autoid-config:/config \
    -it gcr.io/forgerock-autoid/deployer:2021.8.3 create-template
  12. Configure your upgraded system by editing the ~/autoid-config/vars.yml , ~/autoid-config/hosts , and ~/autoid-config/vault.yml files on the deployer machine.

    You must keep your configuration settings consistent from one system to another.
  13. Download the images. This step downloads software dependencies needed for the deployment and places them in the autoid-packages directory. Make sure you are in the ~/autoid-config directory.

    $ ./deployer.sh download-images
  14. Create a tar file containing all of the Autonomous Identity binaries.

    $ tar czf autoid-packages.tgz deployer.sh autoid-packages/* 
  15. Copy the autoid-packages.tgz , deployer.sh , and SSH key (id_rsa ) to a portable hard drive.

  16. On the air-gapped target machine, backup your previous ~/autoid-config directory, and then create a new ~/autoid-config directory.

    $ mkdir ~/autoid-config
  17. Copy the autoid-package.tgz tar file from the portable storage device.

  18. Unpack the tar file.

    $ tar xf autoid-packages.tgz -C ~/autoid-config
  19. Copy the SSH key to the ~/autoid-config directory.

  20. Change the privileges to the file.

    $ chmod 400 ~/autoid-config/id_rsa
  21. Change to the configuration directory.

    $ cd ~/autoid-config
  22. Import the deployer image.

    $ ./deployer.sh import-deployer

    You should see:

    …​
    db631c8b06ee: Loading layer [=============================================⇒]   2.56kB/2.56kB
    2d62082e3327: Loading layer [=============================================⇒]  753.2kB/753.2kB
    Loaded image: gcr.io/forgerock-autoid/deployer:2021.8.3
  23. Create the configuration template using the create-template command. This command creates the configuration files: ansible.cfg , vars.yml , vault.yml and hosts.

    $ ./deployer.sh create-template

    You should see:

    Config template is copied to host machine directory mapped to /config
  24. Configure your upgraded system by editing the ~/autoid-config/vars.yml , ~/autoid-config/hosts , and ~/autoid-config/vault.yml files on the deployer machine.

    You must keep your configuration settings consistent from one system to another.
  25. Run the upgrade.

    1. If you are upgrading from version 2021.8.0, run the following:

      $ ./deployer.sh debug upgrade_2020_8
      
      $ docker stack rm configuration-service consul-server consul-client nginx jas swagger-ui ui api notebook
      
      $ ./deployer.sh debug patch_log4j
    2. If you are upgrading from version 2021.8.1 or 2021.8.2, run the following:

      $ ./deployer.sh debug patch_log4j
  26. Log out and then log back in to Autonomous Identity.

You have successfully upgraded your Autonomous Identity server to 2021.8.3.

Upgrade from Autonomous Identity 2021.3.x to 2021.8.3

The following instruction is for an upgrade from Autonomous Identity 2021.3.x (2021.3.0, 2021.3.1, 2021.3.2, 2021.3.3, 2021.3.4, and 2021.3.5) to version 2021.8.3 in non air-gapped deployments.

As a reminder, upgrade from 2021.3.x to 2021.8.3 requires multiple updates to account for numerous backend component and feature changes for each major release:

  • 2021.3.0–2021.3.4 → 2021.3.5

  • 2021.3.5 → 2021.8.0

  • 2021.8.0 → 2021.8.3

Upgrade from 2021.3.x to version 2021.8.3:

  1. If you are on version 2021.3.0–2021.3.4, you must upgrade to the latest patch release to version 2021.3.5. See Upgrading Autonomous Identity to 2021.3.5.

  2. From version 2021.3.5, upgrade to version 2021.8.0. Follow the instructions in Upgrading Autonomous Identity from 2021.3.5 to 2021.8.0.

  3. From version 2021.8.0, upgrade to the latest patch version, 2021.8.3. Follow the instructions in Upgrade from Autonomous Identity 2021.8.0 to 2021.8.3.