Chapter 11. Upgrading
You can upgrade your existing Ansible Automation Platform deployment to the newer version. The upgrade process covers upgrading the automation hub, automation controller, and extension nodes. The upgrade process takes roughly the same amount of time as a Ansible Automation Platform deployment install. You are required to create a backup before running the upgrade.
Ansible Automation Platform from GCP Marketplace supports sequential upgrades. All upgrades should be no more than one major version behind the version you are currently upgrading to. For example, to upgrade Ansible Automation Platform to 2.4.20230630, you must be on version 2.3.20230221.
Logging and monitoring must be disabled before running the upgrade. Follow these instructions to toggle off monitoring and logging for your current version before beginning the upgrade.
When the upgrade has completed, logging and monitoring can be reenabled by following these instructions.
Prerequisites
- Docker must be installed to run the upgrade playbook.
-
A Linux or macOS system, where the
ansible-on-clouds-opscontainer image will run. - The upgrade process requires several volumes to be mounted. Prepare a fresh directory to be used for this process.
The following procedures form the upgrade process:
Backup your Ansible Automation Platform 2.3 stack.
- Follow the Ansible on Clouds 2.3 backup instructions.
Upgrade Ansible Automation Platform
- Pull the ansible-on-clouds-ops 2.4 container image
- Ensure minimum required permissions are met
- Generate the data file
- Update the data file
- Begin upgrading Ansible Automation Platform by running the operational container
(Optional) Restore the stack from a backup.
- Follow the Ansible on Clouds 2.3 restore instructions.
11.1. Backup before upgrade
Before starting the upgrade of your Ansible Automation Platform environment, you must first take a backup of your environment at its current version.
To backup your Ansible Automation Platform environment at the earlier version, follow the Ansible on Clouds 2.3 backup instructions.
11.2. Upgrade Ansible Automation Platform
11.2.1. Pulling the ansible-on-clouds-ops container image
Procedure
Pull the Docker image for Ansible on Clouds operational container with the same tag as the version you want to upgrade to.
NoteBefore pulling the docker image, ensure you are logged in to registry.redhat.io using docker. Use the following command to login to registry.redhat.io.
$ docker login registry.redhat.io
For more information about registry login, see Registry Authentication
NoteThe Ansible on Clouds operational image tag must match the version that you want to upgrade to. For example, if your foundation deployment version is 2.3.20230221, pull the operational image with tag 2.4.20230630 to upgrade to version 2.4.20230630.
$ export IMAGE=registry.redhat.io/ansible-on-clouds/ansible-on-clouds-ops-rhel9:2.4.20230630 $ docker pull $IMAGE --platform=linux/amd64
11.2.2. Required permissions
You must have the following GCP IAM permissions to upgrade the stack:
required-roles: - Service Account User - Compute Instance Admin (v1) required-permissions: - compute.healthChecks.update - compute.healthChecks.use - compute.healthChecks.useReadOnly - compute.regionBackendServices.update - iap.tunnelInstances.accessViaIAP - runtimeconfig.variables.get - secretmanager.locations.get - secretmanager.locations.list - secretmanager.secrets.create - secretmanager.secrets.delete - secretmanager.secrets.get - secretmanager.secrets.list - secretmanager.secrets.update - secretmanager.versions.access - secretmanager.versions.add - secretmanager.versions.disable - secretmanager.versions.enable - secretmanager.versions.get - secretmanager.versions.list
11.2.3. Generating the data file
The commands in this section create a directory and populate it with an empty data template that, when populated, is used during the upgrade.
Procedure
Run the following commands to generate the required data file.
# Create a folder to hold the configuration files $ mkdir command_generator_data
Populate the
command_generator_datafolder with the configuration file template.NoteOn Linux, any file or directory created by the command generator is owned by
root:rootby default. To change the ownership of the files and directories, you can run thesudo chmodcommand after the files are created. For more information, read Command generator - Linux files owned by root.$ docker run --rm -v $(pwd)/command_generator_data:/data $IMAGE \ command_generator_vars gcp_upgrade \ --output-data-file /data/extra_vars.yml
After running these commands, a
command_generator_data/extra_vars.ymltemplate file is created. This template file resembles the following:gcp_upgrade: ansible_config_path: cloud_credentials_path: deployment_name: extra_vars: gcp_backup_taken: gcp_compute_region: gcp_compute_zone:
11.2.4. Updating the data file
You must populate the data file before triggering the upgrade. Each parameter is required unless it is noted as optional. If the parameter is noted as optional, both its key and value can be removed from the data file.
-
ansible_config_path(Optional) Only use if overriding with a customansible_config. -
cloud_credentials_pathis the path to your GCP credentials file. deployment_nameis the name of the foundation deployment.- This is the same name you used when you deployed the foundation.
-
gcp_backup_takenis the verification that a manual backup of the current deployment was recently created prior to running this upgrade. Usetruehere to verify a recent backup was created. -
gcp_compute_regionis the GCP region that you provided when deploying foundation deployment. If you have not provided a region when deploying the foundation, use the default regionus-east1here. -
gcp_compute_zoneis the GCP zone that you provided when deploying foundation deployment. If you have not provided a zone when deploying the foundation, use the defaultus-east1-bhere.
After populating the data file, it should resemble the following.
The following values are provided as examples:
gcp_upgrade:
ansible_config_path:
cloud_credentials_path: ~/secrets/GCP-secrets.json
deployment_name: AnsibleAutomationPlatform
extra_vars:
gcp_backup_taken: true
gcp_compute_region: us-east1
gcp_compute_zone: us-east1-b11.2.5. Running the upgrade playbook
Ansible Automation Platform upgrade to 2.4.20230630 updates the protocol of its internal load balancers. If additional networking configurations were added after installation, they can also require updating to ensure connectivity. For more information, read the Upgrade note.
To run the upgrade, run the command generator to generate the upgrade CLI command:
$ docker run --rm -v $(pwd)/command_generator_data:/data $IMAGE command_generator --data-file /data/extra_vars.yml
This generates the following command:
----------------------------------------------- docker run --rm --env PLATFORM=GCP -v ~/secrets/GCP-secrets.json:/home/runner/.gcp/credentials:ro --env ANSIBLE_CONFIG=../gcp-ansible.cfg --env DEPLOYMENT_NAME=AnsibleAutomationPlatform --env GENERATE_INVENTORY=true $IMAGE redhat.ansible_on_clouds.gcp_upgrade \ -e 'gcp_deployment_name=AnsibleAutomationPlatform \ gcp_service_account_credentials_json_path=/home/runner/.gcp/credentials \ gcp_compute_region=us-east1 gcp_compute_zone=us-east1-b gcp_backup_taken=True' ===============================================
Run the given upgrade command to trigger the upgrade.
$ docker run --rm --env PLATFORM=GCP -v ~/secrets/GCP-secrets.json:/home/runner/.gcp/credentials:ro \ --env ANSIBLE_CONFIG=../gcp-ansible.cfg \ --env DEPLOYMENT_NAME=AnsibleAutomationPlatform \ --env GENERATE_INVENTORY=true $IMAGE redhat.ansible_on_clouds.gcp_upgrade \ -e 'gcp_deployment_name=AnsibleAutomationPlatform \ gcp_service_account_credentials_json_path=/home/runner/.gcp/credentials \ gcp_compute_region=us-east1 gcp_compute_zone=us-east1-b gcp_backup_taken=True'
The upgrade can take some time to complete, but can take longer depending on the number of extension nodes on the system. A successful upgrade is marked by the log below.
TASK [redhat.ansible_on_clouds.standalone_gcp_upgrade : [upgrade] Show GCP current version] *** ok: [localhost] => { "msg": "gcp_current_version: 2.3.20230221-00" }- Your Ansible Automation Platform from GCP Marketplace deployment is now upgraded to a newer version and you can log in to Red Hat Ansible Automation Platform automation controller and automation hub using your deployment credentials.
11.3. Restore from backup
If you would like to restore the earlier version of your Ansible Automation Platform environment to the state it was in before the upgrade, follow the Ansible on Clouds 2.3 restore instructions.