Chapter 2. Upgrading to Red Hat Ansible Automation Platform 2.6
To upgrade your Red Hat Ansible Automation Platform, start by reviewing Planning your upgrade to ensure a successful upgrade. You can then download the desired version of the Ansible Automation Platform installer, configure the inventory file in the installation bundle to reflect your environment, and then run the installer.
In Ansible Automation Platform 2.6, while the automation controller’s API remains for backward compatibility, new installations must use the platform gateway API for managing organizations, teams, and users. Using the legacy API will introduce a delay of up to 15 minutes before changes are synchronized to all components, including Event-Driven Ansible controller.
2.1. Upgrade prerequisites Copy linkLink copied to clipboard!
Before you begin the upgrade process, review the following considerations to plan and prepare your Ansible Automation Platform deployment:
2.1.1. Ansible Automation Platform requirements Copy linkLink copied to clipboard!
- Verify that you have a valid subscription before upgrading from a previous version of Ansible Automation Platform. Existing subscriptions are carried over during the upgrade process.
- Review Planning your upgrade to understand the upgrade requirements and scenarios, and Tested deployment models for the RPM topologies and infrastructure.
- Ensure that you are on Ansible Automation Platform 2.4 or 2.5 before upgrading to 2.6. You can only upgrade from Ansible Automation Platform 2.4 or 2.5 to 2.6.
Upgrade to the latest version of Ansible Automation Platform 2.4 or 2.5 before upgrading to Red Hat Ansible Automation Platform 2.6.
Important- When upgrading from Ansible Automation Platform 2.4 to 2.6, the API endpoints for the automation controller, automation hub, and Event-Driven Ansible controller are all available for use. These APIs are being deprecated and will be disabled in an upcoming release. This grace period is to allow for migration to the new APIs put in place with the platform gateway.
- If you upgraded from Ansible Automation Platform 2.4 to 2.5, you must migrate your authentication methods and users before upgrading to 2.6 as that legacy authenticator functionality was removed. For information about migrating users, see Migrating Single Sign-On (SSO) users in RPM Upgrade and Migration guide for 2.5.
- Back up your Ansible Automation Platform environment before upgrading in case any issues occur. See Backing up your Ansible Automation Platform instance and Backup and recovery for operator environments for the specific topology of the environment.
- Capture your inventory or instance group details before upgrading.
Review the platform gateway requirements:
- Ansible Automation Platform 2.4 to 2.6 upgrades include the platform gateway. Ensure you review the 2.6 Network ports and protocols for architectural changes.
- Platform gateway has a number of associated inventory file variables, some of which are required. For details of the new and changed variables for 2.6, see Appendix A. Inventory file variables.
When upgrading from Ansible Automation Platform 2.4 to 2.6, connections to the platform gateway URL might fail on the platform gateway UI if you are using the automation controller behind a load balancer. The following error message is displayed:
Error connecting to Controller API
To resolve this issue, for each automation controller host, add the platform gateway URL as a trusted source in the
CSRF_TRUSTED_ORIGIN
setting in the settings.py file for each automation controller host. You must then restart each automation controller host so that the URL changes are implemented. For more information, see Upgrading in Troubleshooting Ansible Automation Platform.
Review the centralized Redis instance offered by Ansible Automation Platform for both standalone and clustered topologies.
- Ansible Automation Platform 2.6 offers a centralized Redis instance in both standalone and clustered topologies. For information on how to configure Redis, see Configuring Redis in the RPM installation guide.
- 6 VMs are required for a Redis high availability (HA) compatible deployment. Redis can be colocated on each Ansible Automation Platform component VM except for automation controller, execution nodes, or the PostgreSQL database.
- External Redis is not supported for RPM-based deployments of Ansible Automation Platform.
Limitation:
- Upgrade of Event-Driven Ansible 2.5 to 2.6 is supported, but upgrade from Event-Driven Ansible 2.4 to 2.6 is not supported. Database migrations between Event-Driven Ansible 2.4 and Event-Driven Ansible 2.6 are not compatible. If you are upgrading from Ansible Automation Platform 2.4 to 2.6 and you deployed Event-Driven Ansible, you must first remove the Event-Driven Ansible 2.4 database and then upgrade your platform to 2.6. For information about the procedure, see Removing Event-Driven Ansible 2.4 database.
2.1.2. System requirements Copy linkLink copied to clipboard!
Type | Description | Notes |
---|---|---|
Subscription | Valid Red Hat Ansible Automation Platform subscription | |
Operating system | Red Hat Enterprise Linux 9.4 or later minor versions of Red Hat Enterprise Linux 9 | Red Hat Ansible Automation Platform are also supported on OpenShift, see Installing on OpenShift Container Platform for more information. |
CPU architecture | x86_64, AArch64, s390x (IBM Z), ppc64le (IBM Power) | |
Ansible-core | Ansible-core version 2.16 or later | Ansible Automation Platform uses the system-wide ansible-core package to install the platform, but uses ansible-core 2.16 for both its control plane and built-in execution environments. |
Browser | A currently supported version of Mozilla Firefox or Google Chrome. | |
Database |
|
|
2.1.3. Database requirements Copy linkLink copied to clipboard!
Ansible Automation Platform can work with two varieties of database:
- Database installed with Ansible Automation Platform - This database consists of a PostgreSQL installation done as part of an Ansible Automation Platform installation using PostgreSQL packages provided by Red Hat.
- Customer provided or configured database - This is an external database that is provided by the customer, whether on bare metal, virtual machine, container, or cloud hosted service. Ansible Automation Platform requires customer provided (external) database to have ICU support.
- PostgreSQL user passwords are hashed with SCRAM-SHA-256 secure hashing algorithm before storing in the database.
- Ensure that you back up your Ansible Automation Platform environment before upgrading in case any issues occur. See Backup and restore and Backup and recovery for operator environments for the specific topology of the environment.
2.1.4. User privileges Copy linkLink copied to clipboard!
Ensure a dedicated non-root user is configured on the Red Hat Enterprise Linux host.
- This user requires sudo or other Ansible supported privilege escalation (sudo is recommended) to perform administrative tasks during the installation.
- This user is responsible for the installation of RPM Ansible Automation Platform.
- You can obtain root access either through the sudo command, or through privilege escalation. You can de-escalate privileges from root to users such as AWX, PostgreSQL, Event-Driven Ansible, or Pulp.
- An NTP client is configured on each node.
2.2. Backing up your Ansible Automation Platform instance Copy linkLink copied to clipboard!
Back up an existing Ansible Automation Platform instance by running the .setup.sh
script with the backup_dest
flag, which saves the content and configuration of your current environment. Use the compression flags use_archive_compression
and use_db_compression
to compress the backup artifacts before they are sent to the host running the backup operation.
Procedure
- Navigate to your Ansible Automation Platform installation directory.
Run the
./setup.sh
script following the example below:./setup.sh -e 'backup_dest=/ansible/mybackup' -e
$ ./setup.sh -e 'backup_dest=/ansible/mybackup' -e 'use_archive_compression=true' 'use_db_compression=true @credentials.yml -b
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Where:
-
backup_dest
: Specifies a directory to save your backup to. use_archive_compression=true
anduse_db_compression=true
: Compresses the backup artifacts before they are sent to the host running the backup operation.You can use the following variables to customize the compression:
-
For global control of compression for filesystem related backup files:
use_archive_compression=true
For component-level control of compression for filesystem related backup files:
<componentName>_use_archive_compression
For example:
-
automationgateway_use_archive_compression=true
-
automationcontroller_use_archive_compression=true
-
automationhub_use_archive_compression=true
-
automationedacontroller_use_archive_compression=true
-
-
For global control of compression for database related backup files:
use_db_compression=true
For component-level control of compression for database related backup files:
<componentName>_use_db_compression=true
For example:
-
automationgateway_use_db_compression=true
-
automationcontroller_use_db_compression=true
-
automationhub_use_db_compression=true
-
automationedacontroller_use_db_compression=true
-
-
For global control of compression for filesystem related backup files:
-
Result
After a successful backup, a backup file is created at /ansible/mybackup/automation-platform-backup-<date/time>.tar.gz
.
2.3. Choosing and obtaining a Red Hat Ansible Automation Platform installer Copy linkLink copied to clipboard!
Choose the Red Hat Ansible Automation Platform installer you need based on your Red Hat Enterprise Linux environment internet connectivity. Review the following scenarios and decide on which Red Hat Ansible Automation Platform installer meets your needs.
A valid Red Hat customer account is required to access Red Hat Ansible Automation Platform installer downloads on the Red Hat Customer Portal.
2.3.1. Installing with internet access Copy linkLink copied to clipboard!
Choose the Red Hat Ansible Automation Platform installer if your Red Hat Enterprise Linux environment is connected to the internet. Installing with internet access retrieves the latest required repositories, packages, and dependencies. Choose one of the following ways to set up your Ansible Automation Platform installer.
Procedure
Tarball install
- Navigate to the Red Hat Ansible Automation Platform download page.
- In the Product software tab, click for the Ansible Automation Platform <latest-version> Setup.
Extract the files:
tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz
$ tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
RPM install
Install the Ansible Automation Platform Installer Package.
v.2.6 for RHEL 9 for x86-64:
sudo dnf install --enablerepo=ansible-automation-platform-2.6-for-rhel-9-x86_64-rpms ansible-automation-platform-installer
$ sudo dnf install --enablerepo=ansible-automation-platform-2.6-for-rhel-9-x86_64-rpms ansible-automation-platform-installer
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Notednf install
enables the repo as the repo is disabled by default.When you use the RPM installer, the files are placed under the
/opt/ansible-automation-platform/installer
directory.
2.3.2. Installing without internet access Copy linkLink copied to clipboard!
Use the Red Hat Ansible Automation Platform Bundle installer if you are unable to access the internet, or would prefer not to install separate components and dependencies from online repositories. Access to Red Hat Enterprise Linux repositories is still needed. All other dependencies are included in the tar archive.
Procedure
- Navigate to the Red Hat Ansible Automation Platform download page.
- In the Product software tab, click for the Ansible Automation Platform <latest-version> Setup Bundle.
Extract the files:
tar xvzf ansible-automation-platform-setup-bundle-<latest-version>.tar.gz
$ tar xvzf ansible-automation-platform-setup-bundle-<latest-version>.tar.gz
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4. Setting up the inventory file Copy linkLink copied to clipboard!
Before upgrading your Red Hat Ansible Automation Platform installation, edit the inventory
file so that it matches your desired configuration. You can keep the same parameters from your existing Ansible Automation Platform deployment or you can modify the parameters to match any changes to your environment.
You can find sample inventory files in the Test topologies GitHub repository, or in our Tested deployment models guide.
Procedure
Navigate to the installation program directory.
- Bundled installer
cd ansible-automation-platform-setup-bundle-2.6-4-x86_64
$ cd ansible-automation-platform-setup-bundle-2.6-4-x86_64
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - Online installer
cd ansible-automation-platform-setup-2.6-4
$ cd ansible-automation-platform-setup-2.6-4
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
Open the
inventory
file for editing. Modify the
inventory
file to provision new nodes, deprovision nodes or groups, and import or generate automation hub API tokens.You can use the same
inventory
file from an existing Ansible Automation Platform installation if there are no changes to the environment.NoteProvide a reachable IP address or fully qualified domain name (FQDN) for all hosts to ensure that users can synchronize and install content from Ansible automation hub from a different node. Do not use
localhost
. Iflocalhost
is used, the upgrade will be stopped as part of preflight checks.Provision new nodes in a cluster, by adding new nodes alongside existing nodes in the
inventory
file as follows:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.5. Removing Event-Driven Ansible 2.4 database Copy linkLink copied to clipboard!
Ansible Automation Platform 2.6 supports upgrades from Ansible Automation Platform 2.4 environments for all components, except for Event-Driven Ansible. Database migrations between Event-Driven Ansible 2.4 and Event-Driven Ansible 2.6 are not compatible.
If you are upgrading from Ansible Automation Platform 2.4 to 2.6, you must first remove the Event-Driven Ansible 2.4 database. A new Event-Driven Ansible 2.6 database gets created automatically after the upgrade. You can then reconnect Automation Decisions (Event-Driven Ansible controller) to Automation Execution (automation controller) to run rulebook activations.
When upgrading from Ansible Automation Platform 2.5 to 2.6, the Event-driven Ansible component will be updated automatically. You are not required to delete the existing Event-Driven Ansible 2.5 database before upgrading your platform to 2.6.
Procedure
- Shut down the old Event-Driven Ansible 2.4 host.
Log in to your database host with a user that has superuser privileges.
# psql -h <hostname> -U <username>
- When prompted, enter your password.
Delete the existing Event-Driven Ansible 2.4 database by using the following command:
DROP DATABASE automationedacontroller
- When prompted, reenter your password.
Next steps
- Run the Ansible Automation Platform installer setup script.
- After the upgrade is completed, reconnect Automation Decisions (Event-Driven Ansible controller) to Automation Execution (automation controller) to run rulebook activations successfully.
2.6. Running the Red Hat Ansible Automation Platform installer setup script Copy linkLink copied to clipboard!
You can run the setup script once you have finished updating the inventory
file.
Procedure
Run the
setup.sh
script:./setup.sh
$ ./setup.sh
Copy to Clipboard Copied! Toggle word wrap Toggle overflow The installation will begin.
2.7. Verifying user migration Copy linkLink copied to clipboard!
During the upgrade to Ansible Automation Platform 2.6, controller user accounts are converted into platform user accounts. Controller administrators retain their administrative privileges, but they are converted into platform administrator privileges.
Other controller accounts become platform users, and their existing permissions are mapped over appropriately after an initial password reset. Users with existing accounts associated with other components (like private automation hub and Event-Driven Ansible) must have their passwords reset by their administrator before they can log in.
Authenticator configurations are automatically migrated. SSO and LDAP accounts do not require any manual migration steps, including password resets, with the exception of accounts that use a certificate from the trust store. See Configuring authentication in the Ansible Automation Platform for more information on migrating authentication configurations that use a custom certificate.
After your upgrade to Ansible Automation Platform 2.6 is complete, verify that you can log in to the upgraded platform.
Procedure
If you have a controller account that has been converted to a platform gateway account for Ansible Automation Platform 2.6:
- Log into your upgraded platform instance with your controller credentials.
If you have a component-level account (such as an account associated with private automation hub or Event-Driven Ansible):
- Request a password reset from your administrator and log into the upgraded platform with your new password.
2.8. Automation controller and automation hub 2.4 and Event-Driven Ansible 2.6 with unified UI upgrades Copy linkLink copied to clipboard!
Ansible Automation Platform 2.6 supports upgrades from Ansible Automation Platform 2.4 environments for all components, with the exception of Event-Driven Ansible. You can also configure a mixed environment with Event-Driven Ansible from 2.6 connected to a legacy 2.4 cluster. Combining install methods (OCP, RPM, Containerized) within such a topology is not supported by Ansible Automation Platform.
If you are running the 2.4 version of Event-Driven Ansible in production, before you upgrade, contact Red Hat support or your account representative for more information on how to move to Ansible Automation Platform 2.6.
Supported topologies described in this document assume that:
- 2.4 services will only include automation controller and automation hub.
- 2.6 parts will always include Event-Driven Ansible and the unified UI (platform gateway).
- Combining installation methods for these topologies is not supported.
2.8.1. Upgrade considerations Copy linkLink copied to clipboard!
- You must maintain two separate inventory files: one for the 2.4 services and one for the 2.6 services.
- You must maintain two separate installations within this scenario: one for the 2.4 services and one for the 2.6 services.
- You must upgrade the two separate installations separately.
To upgrade to a consistent component version topology, consider the following:
- You must manually combine the inventory file configuration from the 2.4 inventory into the 2.6 inventory and run the upgrade on the 2.6 inventory file ONLY.
- You must be using an external database for both the 2.4 inventory and 2.6 inventory.
- Customers using managed database instances for either 2.4 or 2.6 inventory must migrate to an external database first, before upgrading.
2.8.2. Using migration path for 2.4 instances with managed databases Copy linkLink copied to clipboard!
Use this procedure if you have migration path for 2.4 instances with managed databases.
Prerequisites
- An inventory from 2.4 for automation controller and automation hub and a 2.6 inventory for unified UI (platform gateway) and Event-Driven Ansible. You must run upgrades on 2.4 services (using the inventory file to specify only automation controller and automation hub VMs) to get them to the initial version of Ansible Automation Platform 2.6 first. When all the services are at the same version, run an upgrade (using a complete inventory file) on all the services to go to the latest version of Ansible Automation Platform 2.6.
DO NOT upgrade Event-Driven Ansible and the unified UI (platform gateway) to the latest version of Ansible Automation Platform 2.6 without first upgrading the individual services (automation controller and automation hub) to the initial version of Ansible Automation Platform 2.6.
- Ensure you have upgraded to the latest version of Ansible Automation Platform 2.4 before upgrading your Red Hat Ansible Automation Platform.
Procedure
For standalone node managed database
- Convert the database node to an external one, removing it from the inventory. The PostgreSQL node will continue working and will not lose the Ansible Automation Platform-provided setup, but you are responsible for managing its configuration afterward.
For collocated managed database
- Back up
- Restore with standalone managed database node instead of collocated
- Unmanaged standalone database
2.8.3. Using Migration path for 2.4 services with 2.6 services Copy linkLink copied to clipboard!
If you installed Ansible Automation Platform 2.6 to use Event-Driven Ansible in a supported scenario, you can upgrade your Ansible Automation Platform 2.4 automation controller and automation hub to Ansible Automation Platform 2.6 by following the procedure in this section.
Prerequisites
- An inventory from 2.4 for automation controller and automation hub and a 2.6 inventory for unified UI (platform gateway) and Event-Driven Ansible. You must run upgrades on 2.4 services (using the inventory file to specify only automation controller and automation hub VMs) to get them to the initial version of Ansible Automation Platform 2.6 first. When all the services are at the same version, run an upgrade (using a complete inventory file) on all the services to go to the latest version of Ansible Automation Platform 2.6.
DO NOT upgrade Event-Driven Ansible and the unified UI (platform gateway) to the latest version of Ansible Automation Platform 2.6 without first upgrading the individual services (automation controller and automation hub) to the initial version of Ansible Automation Platform 2.6.
- Ensure you have upgraded to the latest version of Ansible Automation Platform 2.4 before upgrading your Red Hat Ansible Automation Platform.
Procedure
Merge 2.4 inventory data into the 2.6 inventory.
The example below shows the inventory file for automation controller and automation hub for 2.4 and the inventory file for Event-Driven Ansible and the unified UI (platform gateway) for 2.6, respectively, as the starting point, and what the merged inventory looks like.
Inventory files from 2.4
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Inventory files from 2.6
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Merged Inventory
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Run
setup.sh
The installer upgrades automation controller and automation hub from 2.4 to Ansible Automation Platform 2.6, latest Event-Driven Ansible, and the unified UI (platform gateway) from the fresh install of 2.6 to the latest version of 2.6, and connects automation controller and automation hub properly with the unified UI (platform gateway) node to initialize the unified experience.
Verification
Verify that everything has upgraded to 2.6 and is working properly in one of two ways:
- Perform an SSH to automation controller and Event-Driven Ansible.
-
In the unified UI, navigate to
to verify the RPM versions are at 2.6.