Upgrading Autonomous Identity

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

The upgrade assumes the following:

  • 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 a registry key to log into the ForgeRock Google Cloud Registry (gcr.io). 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.

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

Upgrade to Autonomous Identity 2021.8.1

The following instruction is for an upgrade from Autonomous Identity 2021.3.2 or 2021.8.0 to version 2021.8.1.

Upgrade to version 2021.8.1:

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

    $ mv ~/autoid-config ~/backup-2021.3.2
    $ mv ~/autoid-config ~/backup-2021.8.0
  2. Create a new ~/autoid-config directory.

    $ mkdir ~/autoid-config
  3. Copy your autoid_registry_key.json from your backup directory 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: Tue Oct 15 18:19:14 2021
  7. Stop the stack.

    • For 2021.3.x deployments, run the following:

      $ docker stack rm configuration-service consul-server consul-client nginx jas openldap selfservice 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 openldap
      Removing service selfservice_selfservice
      Removing service swagger-ui_swagger-ui
      Removing service ui_zoran-ui
      Removing service api_zoran-api
      Nothing found in stack: notebook
    • For 2021.8.0 deployments, run the following:

      $ 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. Enter exit to end your SSH session.

  9. From the deployer, repeat the restart Docker command:

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

    $ cd ~/autoid-config
  11. 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
  12. 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.1 create-template
  13. 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. For 2021.3.x to 2021.8.x upgrades, do not copy-n-paste your hosts file as they are slightly different.
  14. 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
  15. SSH to the target node.

  16. Stop the Spark master and workers.

    $ /opt/autoid/spark/spark-3.0.1-bin-hadoop2.7/sbin/stop-all.sh

    You should see:

    localhost: stopping org.apache.spark.deploy.worker.Worker
    stopping org.apache.spark.deploy.master.Master
  17. Exit your SSH session.

  18. Run the upgrade.

    For 2021.8.0 to 2021.8.1:
    $ ./deployer.sh debug upgrade_2020_8
    
    For 2021.3.x to 2021.8.x:
    $ ./deployer.sh upgrade
  19. Log out and then log back in to Autonomous Identity.

  20. Add a reference to the Autonomous Identity UI to your /etc/hosts or DNS server.

    <Public IP Address> autoid-ui.forgerock.com
  21. Redo the attribute mappings. See Set Attribute Mappings.

  22. Then, run the analytics pipeline with a new analytics step, analytics mine:

    $ analytics ingest
    $ analytics train
    $ analytics mine
    $ analytics predict-as-is
    $ analytics predict-recommendation
    $ analytics publish
    $ analytics create-assignment-index
  23. Open a terminal window, and SSH to the target server.

  24. Run the refresh-company-view alias from the command line.

    $ refresh-company-view

    You have successfully upgraded your Autonomous Identity server to 2021.8.1.