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.

Note

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-ops container 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:

  1. Backup your Ansible Automation Platform 2.3 stack.

  2. Upgrade Ansible Automation Platform

    1. Pull the ansible-on-clouds-ops 2.4 container image
    2. Ensure minimum required permissions are met
    3. Generate the data file
    4. Update the data file
    5. Begin upgrading Ansible Automation Platform by running the operational container
  3. (Optional) Restore the stack from a backup.

11.1. Backup before upgrade

Important

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.

    Note

    Before 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

    Note

    The 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

  1. Run the following commands to generate the required data file.

    # Create a folder to hold the configuration files
    $ mkdir command_generator_data
  2. Populate the command_generator_data folder with the configuration file template.

    Note

    On Linux, any file or directory created by the command generator is owned by root:root by default. To change the ownership of the files and directories, you can run the sudo chmod command 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
  3. After running these commands, a command_generator_data/extra_vars.yml template 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 custom ansible_config.
  • cloud_credentials_path is the path to your GCP credentials file.
  • deployment_name is the name of the foundation deployment.

    • This is the same name you used when you deployed the foundation.
  • gcp_backup_taken is the verification that a manual backup of the current deployment was recently created prior to running this upgrade. Use true here to verify a recent backup was created.
  • gcp_compute_region is the GCP region that you provided when deploying foundation deployment. If you have not provided a region when deploying the foundation, use the default region us-east1 here.
  • gcp_compute_zone is the GCP zone that you provided when deploying foundation deployment. If you have not provided a zone when deploying the foundation, use the default us-east1-b here.

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-b

11.2.5. Running the upgrade playbook

Note

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.

  1. 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'
    ===============================================
  2. 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'
  3. 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"
    }
  4. 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.