Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 9. Upgrading Red Hat Ansible Automation Platform Operator on Red Hat OpenShift Container Platform

The Ansible Automation Platform Operator simplifies the installation, upgrade, and deployment of new Red Hat Ansible Automation Platform instances in your OpenShift Container Platform environment.

9.1. Overview
Copy link

You can use this document for help with upgrading Ansible Automation Platform versions 2.4 and 2.5 to 2.5 on Red Hat OpenShift Container Platform. This document applies to upgrades of Ansible Automation Platform 2.5 to later versions of 2.5.

The Ansible Automation Platform Operator manages deployments, upgrades, backups, and restores of automation controller and automation hub. It also handles deployments of AnsibleJob and JobTemplate resources from the Ansible Automation Platform Resource Operator.

Each operator version has default automation controller and automation hub versions. When the operator is upgraded, it also upgrades the automation controller and automation hub deployments it manages, unless overridden in the spec.

OpenShift deployments of Ansible Automation Platform use the built-in Operator Lifecycle Management (OLM) functionality. For more information, see Operator Lifecycle Manager concepts and resources. OpenShift does this by using Subscription, CSV, InstallPlan, and OperatorGroup objects. Most users will not have to interact directly with these resources. They are created when the Ansible Automation Platform Operator is installed from OperatorHub and managed through the Subscriptions tab in the OpenShift console UI. For more information, refer to Accessing the web console.

Subscription tab

9.2. Upgrade considerations
Copy link

If you are upgrading from version 2.4, continue to the Upgrading the Ansible Automation Platform Operator.

If your OpenShift Container Platform version is not supported by the Red Hat Ansible Automation Platform version you are upgrading to, you must upgrade your OpenShift Container Platform cluster to a supported version first.

Refer to the Red Hat Ansible Automation Platform Life Cycle to determine the OpenShift Container Platform version needed.

For information about upgrading your cluster, refer to Updating clusters.

9.3. Prerequisites
Copy link

To upgrade to a newer version of Ansible Automation Platform Operator, you must:

  • Ensure your system meets the system requirements detailed in the Operator topologies section of the Tested deployment models guide.
  • Create AutomationControllerBackup and AutomationHubBackup objects. For help with this see Backup and recovery for operator environments
  • Review the Release notes for the new Ansible Automation Platform version to which you are upgrading and any intermediate versions.

  • Determine the type of upgrade you want to perform. See the Channel Upgrades section for more information.

    Note

    If you are upgrading from AAP 2.4, you are recommended to take a backup of the API call output and save it to a file. For example: curl -k https://<CONTROLLER_FQDN>/api/v2/settings/all/ -u admin:password >> aap24_old_settings_all

9.4. Channel upgrades
Copy link

Upgrading to version 2.5 from Ansible Automation Platform 2.4 involves retrieving updates from a “channel”. A channel refers to a location where you can access your update. It currently resides in the OpenShift console UI.

Update channel

9.4.1. In-channel upgrades
Copy link

Most upgrades occur within a channel as follows:

  1. A new update becomes available in the marketplace, through the redhat-operator CatalogSource.

  2. The system automatically creates a new InstallPlan for your Ansible Automation Platform subscription.

    • If set to Manual, the InstallPlan needs manual approval in the OpenShift UI.

    • If set to Automatic, it upgrades as soon as the new version is available.

      Note

      Set a manual install strategy on your Ansible Automation Platform Operator subscription during installation or upgrade. You will be prompted to approve upgrades when available in your chosen update channel. Stable channels, like stable-2.5, are available for each X.Y release.

  3. A new subscription, CSV, and operator containers are created alongside the old ones. The old resources are cleaned up after a successful install.

9.4.2. Cross-channel upgrades
Copy link

Upgrading between X.Y channels is always manual and intentional. Stable channels for major and minor versions are in the Operator Catalog. Currently, only version 2.x is available, so there are few channels. It is recommended to stay on the latest minor version channel for the latest patches.

If the subscription is set for manual upgrades, you must approve the upgrade in the UI. Then, the system upgrades the Operator to the latest version in that channel.

Note

It is recommended to set a manual install strategy on your Ansible Automation Platform Operator subscription during installation or upgrade. You will be prompted to approve upgrades when they become available in your chosen update channel. Stable channels, such as stable-2.5, are available for each X.Y release.

The containers provided in the latest channel are updated regularly for OS upgrades and critical fixes. This allows customers to receive critical patches and CVE fixes faster. Larger changes and new features are saved for minor and major releases.

For each major or minor version channel, there is a corresponding "cluster-scoped" channel available. Cluster-scoped channels deploy operators that can manage all namespaces, while non-cluster-scoped channels can only manage resources in their own namespace.

Important

Cluster-scoped bundles are not compatible with namespace-scoped bundles. Do not try to switch between normal (stable-2.4 for example) channels and cluster-scoped (stable-2.4-cluster-scoped) channels, as this is not supported.

To upgrade to the latest version of Ansible Automation Platform Operator on OpenShift Container Platform, you can use the following procedure:

Note

If you are on version 2.4, it is recommended to skip 2.5 and upgrade straight to version 2.5.

If you upgraded from 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.

Prerequisites

Important

Upgrading from Event-Driven Ansible 2.4 is not supported. If you are using Event-Driven Ansible 2.4 in production, contact Red Hat before you upgrade.

Procedure

  1. Log in to OpenShift Container Platform.
  2. Navigate to Operators Installed Operators.
  3. Select the Ansible Automation Platform Operator installed on your project namespace.
  4. Select the Subscriptions tab.
  5. Change the channel from stable-2.4 to stable-2.5. An InstallPlan is created for the user.
  6. Click Preview InstallPlan.
  7. Click Approve.
  8. Create a Custom Resource (CR) using the Ansible Automation Platform UI. The automation controller and automation hub UIs remain until all SSO configuration is supported in the platform gateway UI.

After upgrading to the latest version of Ansible Automation Platform Operator on OpenShift Container Platform, you can create an Ansible Automation Platform custom resource (CR) that specifies the names of your existing deployments, in the same namespace.

The following example outlines the steps to deploy a new Event-Driven Ansible setup after upgrading to the latest version, with existing automation controller and automation hub deployments already in place.

The Appendix contains more examples of Ansible Automation Platform CRs for different deployments.

Procedure

  1. Log in to Red Hat OpenShift Container Platform.
  2. Navigate to Operators Installed Operators.
  3. Select your Ansible Automation Platform Operator deployment.
  4. Select the Details tab.
  5. On the Ansible Automation Platform tile click Create instance.
  6. From the Create Ansible Automation Platform page enter a name for your instance in the Name field.

  7. Click YAML view and paste the following YAML (aap-existing-controller-and-hub-new-eda.yml): 

    ---
apiVersion: aap.ansible.com/v1alpha1
kind: AnsibleAutomationPlatform
metadata:
  name: myaap
spec:
  # Development purposes only
  no_log: false

  controller:
    name: existing-controller #obtain name from controller CR
    disabled: false

  eda:
    disabled: false

  hub:
    name: existing-hub
    disabled: false

  8. Click Create.

    Note

    You can override the operator’s default image for automation controller, automation hub, or platform-resource app images by specifying the preferred image on the YAML spec. This enables upgrading a specific deployment, like a controller, without updating the operator.

    The recommended approach however, is to upgrade the operator and use the default image values.

    Verification

    Navigate to your Ansible Automation Platform Operator deployment and click All instances to verify whether all instances have deployed correctly. You should see the Ansible Automation Platform instance and the deployed AutomationController, EDA, and AutomationHub instances here.

Alternatively, you can verify whether all instances deployed correctly by running oc get route in the command line.

After a successful upgrade to Ansible Automation Platform 2.5, the next crucial step is migrating your users to the latest version of the platform.

User data and legacy authentication settings from automation controller and private automation hub are carried over during the upgrade process and allow seamless initial access to the platform after upgrade. Customers can log in without additional action.

However, to fully transition authentication to use all of the features and capabilities of the 2.5 platform gateway, a manual process is required post-upgrade to leverage the new authentication framework. In the context of upgrading to Ansible Automation Platform 2.5, this manual process is referred to as migration.

There are important notes and considerations for each type of user migration, including the following:

  • Admin users
  • Normal users
  • SSO users
  • LDAP users

Be sure to read through the important notes highlighted for each user type to help make the migration process as smooth as possible.

Upgrades from Ansible Automation Platform 2.4 to 2.5 allows for the migration of administrators for each component with their existing component-level admin privileges maintained. However, escalation of privileges to platform gateway administrator is not automatic during the upgrade process. This ensures a secure privilege escalation process that can be customized to meet the organization’s specific needs.

Component-level admin privileges are retained: Administrators for automation controller and automation hub will retain their existing admin privileges for those respective services post-upgrade. For example, an admin of automation controller will continue to have full administration privileges for automation controller resources.

Escalation to platform gateway admin must be manually configured post-upgrade: During the upgrade process, admin privileges for individual services are not automatically translated to platform administrator privileges. Escalation to platform gateway admin must be granted by the platform administrator after upgrade and migration. Each service admin retains the original scope of their access until the access is changed.

As a platform administrator, you can escalate a user’s privileges by selecting the Ansible Automation Platform Administrator checkbox. Only a platform administrator can escalate privileges.

Note

Users previously designated as automation controller or automation hub administrators are labeled as Normal in the User type column of the Users list view. This is a mischaracterization. You can verify that these users have, in fact, retained their service level administrator privileges, by editing the account:

9.7.2. Migrating admin users
Copy link

Follow this procedure to migrate admin users.

Prerequisites

  • Review current admin roles for the individual services in your current deployment.
  • Confirm the users who will require platform gateway admin rights post-upgrade.

Procedure

  1. From the navigation panel of the platform gateway, select Access Management Users.
  2. Select the check box for the user that you want to modify.
  3. Click the Pencil icon and select Edit user.
  4. The Edit user page is displayed where you can see the service level administrator privileges assigned by the User type checkboxes. See Editing a user for more information on these user types.

Previous service accounts are prefixed: Users with accounts on multiple services in 2.4 are migrated as individual users in 2.5 and prefixed to identify the service from which they were migrated. For example, automation hub accounts are prefixed as hub_<username>. Automation controller user names do not include a prefix.

Automation controller user accounts take precedence: When an individual user had accounts on multiple services in 2.4, priority is given to their automation controller account during migration, so those are not renamed.

Component level roles are retained until user migration is complete: When users log in using an existing service account and do not perform the account linking process, only the roles for that specific service account are available. The migration process is completed once the user performs the account linking process. At that time, all roles for all services are migrated into the new platform gateway user account.

9.7.4. Migrating normal users
Copy link

When you upgrade from Ansible Automation Platform 2.4 to 2.5, your existing user account is automatically migrated to a single platform account. However, if you have multiple component accounts (such as, automation controller, private automation hub and Event-Driven Ansible), your accounts must be linked to use the centralized features of the platform.

9.7.4.2. Linking your account
Copy link

Ansible Automation Platform 2.5 provides a centralized location for users, teams and organizations to access the platform’s services and features.

The first time you log in to Ansible Automation Platform 2.5, the platform searches through the existing services to locate a user account with the credentials you entered. When there is a match to an existing account, that account is registered and becomes centrally managed by the platform. Any subsequent component accounts in the system are orphaned and cannot be used to log into the platform.

To address this problem, use the account linking procedure to authenticate from any of your existing component accounts and still be recognized by the platform. Linking accounts associates existing component accounts with the same user profile.

If you have completed the upgrade process and have a legacy Ansible Automation Platform subscription, follow the account linking procedure below to migrate your account to Ansible Automation Platform 2.5.

Prerequisites

  • You have completed the upgrade process and have a legacy Ansible Automation Platform account and credentials.

Procedure

  1. Navigate to the login page for Ansible Automation Platform.
  2. In the login modal, select either I have an automation controller account or I have an automation hub account based on the credentials you have.

  3. On the next screen, enter the legacy credentials for the component account you selected and click Log in.

    Note

    If you are logging in using OIDC credentials, see How to fix broken OIDC redirect after upgrading to AAP 2.5.

  4. If you have successfully linked your account, the next screen shows your username with a green checkmark beside it. If you have other legacy accounts that you want to link, enter those account credentials and click Link to link them to your centralized platform gateway account.
  5. Click Submit to complete linking your legacy accounts.

  6. After your accounts are linked, depending on your authentication method, you might be prompted to create a new username and password. These credentials will replace your legacy credentials for each component account.

    • You can also link your legacy account manually by taking the following steps:
  7. Select your user icon at the top right of your screen, and select User details.
  8. Select the More Actions icon ⋮ > Link user accounts.
  9. Enter the credentials for the account that you want to link.

Troubleshooting

If you encounter an error message telling you that your account could not be authenticated, contact your platform administrator.

Note

If you log into Ansible Automation Platform for the first time and are prompted to change your username, this is an indication that another user has already logged into Ansible Automation Platform with the same username. To proceed with account migration, follow the prompts to change your username. Ansible Automation Platform uses your password to authenticate which account or accounts belong to you.

A diagram of the account linking flow Account linking flow

After you have migrated your user account, you can manage your account from the Access Management menu. See Managing access with role based access control.

9.7.5. Migrating Single Sign-On (SSO) users
Copy link

When upgrading from Ansible Automation Platform 2.4 to 2.5, you must migrate your Single Sign-On (SSO) user accounts if you want to continue using SSO capabilities after the upgrade. Follow the steps in this procedure to ensure a smooth SSO user migration.

9.7.5.1. Key considerations
Copy link

SSO configurations are not migrated automatically during upgrade to 2.5: While the legacy authentication settings are carried over during the upgrade process and allow seamless initial access to the platform after upgrade, SSO configurations must be manually migrated over to a new Ansible Automation Platform 2.5 authentication configuration. The legacy configuration acts as a reference to preserve existing authentication capabilities and facilitate the migration process. The legacy authentication configuration should not be modified directly or used after migration is complete.

SSO migration is supported in the UI: Migration of legacy SSO accounts is supported in 2.5 UI, and is done by selecting your legacy authenticator from the Auto migrate users from list when you configure a new authentication method. This is the legacy authenticator from which to automatically migrate users to a new platform gateway authentication configuration.

Migration of SSO must happen before users log in and start account linking: You must enable the Auto migrate users to setting after configuring SSO in 2.5 and before any users log in.

Note

Ansible Automation Platform 2.4 SSO configurations are renamed during the upgrade process and are displayed in the Authentication Methods list view with a prefix to indicate a legacy configuration: for example, legacy_sso-saml-<entity id>. The Authentication type is also listed as legacy sso. These configurations can not be modified.

Once you set up the auto migrate functionality, you should be able to login with SSO in the platform gateway and it will automatically link any matching accounts from the legacy SSO authenticator.

9.7.6. Migrating LDAP users
Copy link

As a platform administrator upgrading from Ansible Automation Platform 2.4 to 2.5, you must migrate your LDAP user accounts if you want to continue using LDAP authentication capabilities after the upgrade. Follow the steps in this procedure to ensure the smoothest possible LDAP user migration.

There are two primary scenarios for migrating users from legacy authentication systems to LDAP-based authentication:

  1. Legacy user login and account linking
  2. Migration to LDAP without account linking

9.7.6.1. Key considerations
Copy link

LDAP configurations are not migrated automatically during upgrade to 2.5: While the legacy LDAP authentication settings are carried over during the upgrade process and allow seamless initial access to the platform after upgrade, LDAP configurations must be manually migrated over to a new Ansible Automation Platform 2.5 LDAP configuration. The legacy configuration acts as a reference to preserve existing authentication capabilities and facilitate the migration process. The legacy authentication configuration should not be modified directly or used after migration is complete.

UID collision risk: LDAP and legacy password authenticators both use usernames as the UID. This can cause UID collisions between users or users with the same name owned by different people. Any user accounts that are not secure for auto-migration due to UID conflicts must be manually migrated to ensure proper handling. You can manually migrate these users through the API /api/gateway/v1/authenticator_users/ before setting auto-migrations.

Do not log in using legacy LDAP authentication if you do not have a user account in the platform prior to the upgrade: Instead, you must auto migrate directly to LDAP without linking accounts.

9.7.6.2. Legacy user login and account linking
Copy link

Users can log in using their legacy accounts by selecting “I have a <component> account” and entering their credentials (username and password). If the login is successful, they may be prompted to link their account with another component account for example, automation hub and automation controller. If the login credentials are the same for both automation hub and automation controller, account linking is automatically done for that user.

After successful account linking, user accounts from both components are merged into a gateway:legacy external password authenticator. If user accounts are not automatically merged into the gateway:legacy external password authenticator, you must auto migrate directly to LDAP without linking accounts.

For more information about account linking, see Linking your accounts.

If a user is unable to link their accounts because there is no linking option for their automation hub account, you must immediately configure the auto-migrate feature on all legacy password authenticators to target the new gateway LDAP authenticator.

Then, when a user logs in, the platform gateway will automatically migrate the user to the LDAP authenticator if a matching UID is found.

Prerequisites

  • Verify that all legacy accounts are properly linked and merged before proceeding with auto-migration.
  • Verify that there are no UID collisions or ensure they are manually migrated before proceeding with auto-migration.

Procedure

  1. Log in to the Ansible Automation Platform UI.

  2. Set up a new LDAP authentication method in the platform gateway following the steps in Configuring LDAP authentication. This will be the configuration that you will migrate your previous LDAP users to.

    Note

    Ansible Automation Platform 2.4 LDAP configurations are renamed during the upgrade process and are displayed in the Authentication Methods list view prefixed to indicate that it is a legacy configuration, for example, <controller/hub/eda>: legacy_password. The Authentication type is listed as Legacy password. These configurations can not be modified.

  3. Select the legacy LDAP authenticator from the Auto migrate users from list. This is the legacy authenticator you want to use for migrating users to your platform gateway LDAP authenticator.

Once you set up the auto migrate functionality, you should be able to login with LDAP in the platform gateway and any matching accounts from the legacy 2.4 LDAP authenticator will automatically be linked.

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top