Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

RPM upgrade and migration

Red Hat Ansible Automation Platform 2.5

Upgrade and migrate legacy deployments of Ansible Automation Platform

Red Hat Customer Content Services

Abstract

This guide shows you how to upgrade to the latest version of Ansible Automation Platform and migrate legacy virtual environments to automation execution environments.

Providing feedback on Red Hat documentation
Copy link

If you have a suggestion to improve this documentation, or find an error, you can contact technical support at https://access.redhat.com to open a request.

1.1. Ansible Automation Platform upgrades
Copy link

Currently, it is possible to perform Ansible Automation Platform upgrades using one of the following supported upgrade paths.

Important

Upgrading from Event-Driven Ansible 2.4 is not supported. If you are upgrading from Ansible Automation Platform 2.4 to 2.5 and you have deployed Event-Driven Ansible, you must first remove the Event-Driven Ansible 2.4 database and then upgrade your platform to 2.5. For information about the procedure, see Removing Event-Driven Ansible 2.4 database.

Before beginning your upgrade be sure to review the prerequisites and upgrade planning sections of this guide.

Expand

Supported upgrade path

Steps to upgrade

Ansible Automation Platform 2.4 to 2.5

Download the installation package.

Set up your inventory file to match your installation environment. See Tested deployment models for a list of example inventory files.

  1. Back up the platform using automation installer.

Remove Event-Driven Ansible 2.4 database, if you deployed Event-Driven Ansible.

Run the 2.5 installation program over your current Ansible Automation Platform instance.

Link your existing service level accounts to a single unified platform account.

Ansible Automation Platform 2.5 to 2.5.x

Download the installation package.

Set up your inventory file to match your installation environment. See Tested deployment models for a list of example inventory files.

  1. Back up the platform using automation installer.

Run the 2.5 installation program over your current Ansible Automation Platform instance.

Automation controller and automation hub 2.4 and Event-Driven Ansible 2.5 with unified UI upgrades

Upgrade the 2.4 services (using inventory file to only specify automation controller and automation hub VMs) to get them to the initial version of AAP 2.5.

After all the services are at the same version, run a 2.5 upgrade on all the services

You can protect your Ansible Automation Platform environment by backing up the database, configuration files, and keys. Use the ./setup.sh script or playbooks to create compressed artifacts. This ensures a recovery path for single nodes or clusters, including restores, to secondary instances.

Note

Use the installation program matching your current Ansible Automation Platform version for backups, and always use the latest available version for restores. Ensure your PostgreSQL version is supported by checking the System requirements in Planning your installation.

2.1. Backup and restoration considerations
Copy link

Consider the following points when you backup and restore your system:

Disk space

Review your disk space requirements to ensure you have enough room to backup configuration files, keys, other relevant files, and the database of the Ansible Automation Platform installation.

Note

The Ansible Automation Platform database backups are staged on each node at /var/backups/automation-platform through the variable backup_dir. You might need to mount a new volume to /var/backups or change the staging location with the variable backup_dir to prevent issues with disk space before running the ./setup.sh -b script.

System credentials
Confirm you have the required system credentials when working with a local database or a remote database. On local systems, you might need root or sudo access, depending on how credentials are set up. On remote systems, you might need different credentials to grant you access to the remote system you are trying to backup or restore.
Version
You must always use the most recent minor version of a release to backup or restore your Ansible Automation Platform installation version. For example, if the current platform version you are on is 2.5.x, only use the latest 2.5 installer.
Backup file location
  • Default location: If the backup file is placed in the same directory as the ./setup.sh installer, the restore playbook locates it automatically.
  • Non-default location: If your backup file is stored in a different directory, you must specify the path using the restore_backup_file extra variable when running the restore command.

2.2. Back up the Ansible Automation Platform
Copy link

Back up your instance using the setup.sh script to save your environment content and configuration. Use the optional backup_dest flag only to change the default save location. Apply compression flags to reduce artifact size before transmission.

2.2.1. Backup playbook
Copy link

The Ansible Automation Platform installer (install.yml) includes the backup.yml playbook, which automates the backup and restoration of your environment. You can use this playbook to capture critical configuration data and databases for the following components:

  • Platform gateway:

    • The database
    • The SECRET_KEY file

  • Automation controller:

    • The database
    • The SECRET_KEY file
    • The RESOURCE_SERVER key
    • The per-host custom configuration files

  • Automation hub:

    • The database
    • The database_fields.symmetric.key file
    • The SECRET_KEY file
    • The RESOURCE_SERVER key
    • Automation hub pulp content

  • Event-Driven Ansible controller:

    • The database
    • The SECRET_KEY file
    • The RESOURCE_SERVER key

Run the setup script to create a verified archive of your platform database, configurations, and secrets. This ensures your instance is captured in a compatible format for reliable restoration during a system failure or migration.

Procedure

  1. Navigate to your Ansible Automation Platform installation directory.

  2. Run the ./setup.sh script following the example below: 

    $ ./setup.sh -e 'backup_dest=/ansible/mybackup' -e
'use_archive_compression=true' 'use_db_compression=true @credentials.yml -b

    Where:

    • backup_dest: Specifies a directory to save your backup to.
    • backup_dir: Specifies the directory used on the host staging backup files before they are transferred to backup_dest locally.

    • use_archive_compression=true and use_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 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

Result

After a successful backup, a backup file is created at /ansible/mybackup/automation-platform-backup-<date/time>.tar.gz.

2.3. Restore Ansible Automation Platform
Copy link

Restoring your instance using the setup.sh script helps you safely reinstate your environment content and configuration. Use the optional restore_backup_file flag only to change the TAR file location.

2.3.1. Restore playbook
Copy link

Automation controller includes playbooks to backup and restore your installation.

In addition to the install.yml file included with your setup.sh setup playbook, there are also restore.yml files.

The restore backup restores the backed up files and data to a freshly installed and working second instance of automation controller.

When restoring your system, installation program checks to see that the backup file exists before beginning the restoration. If the backup file is not available, your restoration fails.

Note

Make sure that your automation controller hosts are properly set up with SSH keys, user or pass variables in the hosts file, and that the user has sudo access.

2.3.2. Restore the platform to its original state
Copy link

Restore your environment by running the setup.sh script to recover platform data and configurations. Ensure the backup TAR file is available in the default location, or use the optional restore_backup_file flag to specify a custom path before starting.

Procedure

  1. Navigate to your Ansible Automation Platform installation directory.

  2. Run the ./setup.sh script following the example: 

    root@localhost:~# ./setup.sh -e 'restore_backup_file=/path/to/nondefault/backup.tar.gz' -r

    Where: restore_backup_file: Path to the TAR file used for the platform restore.

To upgrade your Red Hat Ansible Automation Platform, start by reviewing Planning your installation 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.

3.1. Prerequisites
Copy link

  • Upgrades to Ansible Automation Platform 2.5 include the platform gateway. Ensure you review the 2.5 Network ports and protocols for architectural changes and Tested deployment models for information on opinionated deployment models.
  • You have reviewed the centralized Redis instance offered by Ansible Automation Platform for both standalone and clustered topologies.
  • Prior to upgrading your Red Hat Ansible Automation Platform, ensure you have reviewed Planning your installation for 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.
  • Before upgrading your Red Hat Ansible Automation Platform, ensure you have upgraded to automation controller 4.5 or later.

  • When upgrading to Ansible Automation Platform 2.5, you must use RPM installer version 2.5-11 or later. If you use an older installer, the installation might fail. If you encounter a failed installation using an older version of the installer, rerun the installation with RPM installer version 2.5-11 or later.

    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

3.2. Ansible Automation Platform upgrade planning
Copy link

Before you begin the upgrade process, review the following considerations to plan and prepare your Ansible Automation Platform deployment:

  • See System requirements in the Planning your installation guide to ensure you have the topologies that fit your use case.

    Note

    2.4 to 2.5 upgrades now include Platform gateway. Ensure you review the 2.5 Network ports and protocols for architectural changes.

    Important

    When upgrading from Ansible Automation Platform 2.4 to 2.5, 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.

  • 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.
  • Back up your Ansible Automation Platform 2.4 environment before upgrading in case any issues occur. See Back up the platform using automation installer and Backup and recovery for operator environments for the specific topology of the environment.
  • Ensure you capture your inventory or instance group details before upgrading.
  • Ensure you have upgraded to the latest version of Ansible Automation Platform 2.4 before upgrading your Red Hat Ansible Automation Platform.
  • Upgrade from Event-Driven Ansible 2.4 to 2.5 is not supported. Database migrations between Event-Driven Ansible 2.4 and Event-Driven Ansible 2.5 are not compatible. If you are upgrading from Ansible Automation Platform 2.4 to 2.5 and you have deployed Event-Driven Ansible, you must first remove the Event-Driven Ansible 2.4 database and then upgrade your platform to 2.5. For information about the procedure, see Removing Event-Driven Ansible 2.4 database.
  • If you are currently running Event-Driven Ansible controller 2.5, it is recommended that you disable all Event-Driven Ansible activations before upgrading to ensure that only new activations run after the upgrade process is complete. For more information, see automation controller and automation hub 2.4 and Event-Driven Ansible 2.5 with unified UI upgrades.
  • Automation controller OAuth applications on the platform UI are not supported for 2.4 to 2.5 migration. See this Knowledgebase article for more information. To learn how to recreate your OAuth applications, see Applications in the Access management and authentication guide.
  • During the upgrade process, user accounts from the individual services are migrated. If there are accounts from multiple services, they must be linked to access the unified platform. See Account linking for details.
  • Ansible Automation Platform 2.5 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.

  • When upgrading from Ansible Automation Platform 2.4 to 2.5, 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 controller host, add the platform gateway URL as a trusted source in the CSRF_TRUSTED_ORIGIN setting in the settings.py file for each controller host. You must then restart each controller host so that the URL changes are implemented. For more information, see Upgrading in Troubleshooting Ansible Automation Platform.

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.

Note

A valid Red Hat customer account is required to access Red Hat Ansible Automation Platform installer downloads on the Red Hat Customer Portal.

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

    1. Navigate to the Red Hat Ansible Automation Platform download page.
    2. In the Product software tab, click Download Now for the Ansible Automation Platform <latest-version> Setup.

    3. Extract the files: 

      $ tar xvzf ansible-automation-platform-setup-<latest-version>.tar.gz

  • RPM install

    1. Install the Ansible Automation Platform Installer Package.

      v.2.5 for RHEL 8 for x86_64: 

      $ sudo dnf install --enablerepo=ansible-automation-platform-2.5-for-rhel-8-x86_64-rpms ansible-automation-platform-installer

      v.2.5 for RHEL 9 for x86-64: 

      $ sudo dnf install --enablerepo=ansible-automation-platform-2.5-for-rhel-9-x86_64-rpms ansible-automation-platform-installer
      Note

      dnf 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.

3.3.1. Installing without internet access
Copy link

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

  1. Navigate to the Red Hat Ansible Automation Platform download page.
  2. In the Product software tab, click Download Now for the Ansible Automation Platform <latest-version> Setup Bundle.

  3. Extract the files: 

    $ tar xvzf ansible-automation-platform-setup-bundle-<latest-version>.tar.gz

3.4. Setting up the inventory file
Copy link

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

  1. Navigate to the installation program directory.

    Bundled installer
    $ cd ansible-automation-platform-setup-bundle-2.5-4-x86_64
    Online installer
    $ cd ansible-automation-platform-setup-2.5-4
  2. Open the inventory file for editing.

  3. 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.

    Note

    Provide 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. If localhost is used, the upgrade will be stopped as part of preflight checks.

  4. Provision new nodes in a cluster, by adding new nodes alongside existing nodes in the inventory file as follows: 

    [automationcontroller]
clusternode1.example.com
clusternode2.example.com
clusternode3.example.com

[all:vars]
admin_password='password'

pg_host='<host_name>'

pg_database='<database_name>'
pg_username='<your_username>'
pg_password='<your_password>'

3.5. Removing Event-Driven Ansible 2.4 database
Copy link

Ansible Automation Platform 2.5 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.5 are not compatible.

If you are upgrading from Ansible Automation Platform 2.4 to 2.5, you must first remove the Event-Driven Ansible 2.4 database. A new Event-Driven Ansible 2.5 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.

Procedure

  1. Shut down the old Event-Driven Ansible 2.4 host.

  2. Log in to your database host with a user that has superuser privileges.

    # psql -h <hostname> -U <username>

  3. When prompted, enter your password.

  4. Delete the existing Event-Driven Ansible 2.4 database by using the following command:

    DROP DATABASE automationedacontroller

  5. When prompted, reenter your password.

Next steps

  1. Run the Ansible Automation Platform installer setup script.
  2. After the upgrade is completed, reconnect Automation Decisions (Event-Driven Ansible controller) to Automation Execution (automation controller) to run rulebook activations successfully.

You can run the setup script once you have finished updating the inventory file.

Procedure

  • Run the setup.sh script: 

    $ ./setup.sh

    The installation will begin.

Ansible Automation Platform 2.5 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.5 connected to a legacy 2.4 cluster. Combining install methods (OCP, RPM, Containerized) within such a topology is not supported by Ansible Automation Platform.

Note

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.5.

Supported topologies described in this document assume that:

  • 2.4 services will only include automation controller and automation hub.
  • 2.5 parts will always include Event-Driven Ansible and the unified UI (platform gateway).
  • Combining installation methods for these topologies is not supported.

3.7.1. Upgrade considerations
Copy link

  • You must have two inventory files as a starting point: one for the 2.4 services and one for the 2.5 services.
  • Before running the upgrade, you must merge the 2.4 inventory into the 2.5 inventory. The platform gateway host must be included in the inventory for the installation program to run successfully.
  • Run the upgrade on the merged 2.5 inventory file only.
  • You must be using an external database for both the 2.4 inventory and 2.5 inventory.
  • Customers using managed database instances for either 2.4 or 2.5 inventory must migrate to an external database first, before upgrading.

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.5 inventory for the unified UI (platform gateway) and Event-Driven Ansible. You must merge both inventories into a single 2.5 inventory file before running the upgrade. The platform gateway host must be included in the inventory for the installation program to run successfully.
Important

Ensure you have upgraded to the latest version of Ansible Automation Platform 2.4 before merging inventories and running the 2.5 upgrade.

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

    1. Back up
    2. Restore with standalone managed database node instead of collocated
    3. Unmanaged standalone database

If you installed Ansible Automation Platform 2.5 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.5 by following the procedure in this section.

Prerequisites

  • An inventory from 2.4 for automation controller and automation hub and a 2.5 inventory for the unified UI (platform gateway) and Event-Driven Ansible. You must merge both inventories into a single 2.5 inventory file before running the upgrade. The platform gateway host must be included in the inventory for the installation program to run successfully.
Important

Ensure you have upgraded to the latest version of Ansible Automation Platform 2.4 before merging inventories and running the 2.5 upgrade.

Procedure

  1. Merge 2.4 inventory data into the 2.5 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.5, respectively, as the starting point, and what the merged inventory looks like.

    Inventory files from 2.4 

    [automationcontroller]
controller-1
controller-2

[automationhub]
hub-1
hub-2

[all:vars]
# Here we have the admin passwd, db credentials, etc.

    Inventory files from 2.5 

    [automationedacontroller]
eda-1
eda-2

[automationgateway]
gw-1
gw-2

[all:vars]
# Here we have admin passwd, db credentials etc.

    Merged Inventory 

    [automationcontroller]
controller-1
controller-2

[automationhub]
hub-1
hub-2

[automationedacontroller]
eda-1
eda-2

[automationgateway]
gw-1
gw-2

[all:vars]
# Here we have admin passwd, db credentials etc from both inventories above

  2. Run setup.sh

    The installation program upgrades all services to the latest version of Ansible Automation Platform 2.5 and connects them to the unified UI (platform gateway).

Verification

  • Verify that everything has upgraded to 2.5 and is working properly in one of two ways:

    • Perform an SSH to automation controller and Event-Driven Ansible.
    • In the unified UI, go to Help → About to verify the RPM versions are at 2.5.

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.

4.1. Key considerations for migrating admin users
Copy link

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:

4.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.

4.3. Key considerations for migrating normal users
Copy link

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.

4.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.

4.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.

4.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.

4.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.

4.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

4.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.

4.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.

Legal Notice
Copy link

Copyright © Red Hat.
Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.
The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.
All other trademarks are the property of their respective owners.
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