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

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.

Chapter 1. Red Hat Ansible Automation Platform 2.5 upgrades

1.1. Ansible Automation Platform upgrades

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’re using Event-Driven Ansible 2.4 in production, contact Red Hat before you upgrade.

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

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.

Back up your Ansible Automation Platform instance.

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.

Back up your Ansible Automation Platform instance.

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

Chapter 2. Upgrading to Red Hat Ansible Automation Platform 2.5

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.

2.1. Prerequisites

  • 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.
  • Prior to upgrading your Red Hat Ansible Automation Platform, ensure you have upgraded to automation controller 2.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.

2.2. Ansible Automation Platform upgrade planning

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.
  • Ensure you have a backup of an Ansible Automation Platform 2.4 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.
  • Ensure you capture your inventory or instance group details before upgrading.
  • Ensure you have upgraded to automation controller 2.5 or later before upgrading your Red Hat Ansible Automation Platform.

  • Upgrades of Event-Driven Ansible version 2.4 to 2.5 are not supported. Database migrations between Event-Driven Ansible 2.4 and Event-Driven Ansible 2.5 are not compatible. For more information, see automation controller and automation hub 2.4 and Event-Driven Ansible 2.5 with unified UI upgrades.

    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.

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

Additional resources

2.3. Choosing and obtaining a Red Hat Ansible Automation Platform installer

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.

2.3.1. Installing with internet access

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.

Tarball install

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.

  3. Extract the files: 

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

RPM install

Procedure

  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

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.

2.3.2. Installing without internet access

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

2.4. Setting up the inventory file

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.

Provisioning new nodes in a cluster

  • Add 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>'

2.5. Backing up your Ansible Automation Platform instance

Back up an existing Ansible Automation Platform instance by running the .setup.sh script with the backup_dir 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

  1. Navigate to your Ansible Automation Platform installation directory.

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

    $ ./setup.sh -e ‘backup_dir=/ansible/mybackup’ -e
‘use_archive_compression=true’ ‘use_db_compression=true’ @credentials.yml -b

    Where:

    • backup_dir: Specifies a directory to save your backup to.

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

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

2.6. Running the Red Hat Ansible Automation Platform installer setup script

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.

Next steps

If you are upgrading from Ansible Automation Platform 2.4 to 2.5, proceed to Linking your account to link your existing service level accounts to a single unified platform account.

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

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 install methods for these topologies is not supported.

2.7.1. Upgrade considerations

  • You must maintain two separate inventory files: one for the 2.4 services and one for the 2.5 services.
  • You must maintain two separate "installations" within this scenario: one for the 2.4 services and one for the 2.5 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.5 inventory and run upgrade on ONLY the 2.5 inventory file.
    • You must be using an external database for both the 2.4 inventory as well as the 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.

Prerequisites

  • An inventory from 2.4 for automation controller and automation hub and a 2.5 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.5 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.5.
Important

DO NOT upgrade Event-Driven Ansible and the unified UI (platform gateway) to the latest version of Ansible Automation Platform 2.5 without first upgrading the individual services (automation controller and automation hub) to the initial version of Ansible Automation Platform 2.5.

  • Ensure you have upgraded to automation controller 2.5 or later before upgrading your Red Hat Ansible Automation Platform.
2.7.1.1. Migration path for 2.4 instances with managed databases

Procedure

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.

Collocated managed database

  1. Backup
  2. Restore with standalone managed database node instead of collocated.
  3. Unmanaged standalone database
2.7.1.2. Migration path for 2.4 services with 2.5 services

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 these steps:

  • 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 

[edacontroller]
eda-1
eda-2

[gateway]
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

[edacontroller]
eda-1
eda-2

[gateway]
gw-1
gw-2

[all:vars]
# Here we have admin passwd, db credentials etc from both inventories above
  • Run setup.sh The installer upgrades automation controller and automation hub from 2.4 to Ansible Automation Platform 2.5.latest, Event-Driven Ansible and the unified UI (platform gateway) from the fresh install of 2.5 to the latest version of 2.5, 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.5 and is working properly in one of two ways:

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

Chapter 3. Ansible Automation Platform post-upgrade steps

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.

3.1. Migrating admin users

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.

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.

3.1.1. Key considerations

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.

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:

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

Only a platform administrator can escalate your privileges.

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.

3.2. Migrating normal users

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.

3.2.1. Key considerations

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.

3.2.2. Additional resources

3.2.3. Linking your account

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.

Prerequisites

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

Procedure

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.

  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:

  1. Select your user icon at the top right of your screen, and select User details.
  2. Select the More Actions icon ⋮ > Link user accounts.
  3. Enter the credentials for the account that you want to link.

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.

3.3. Migrating Single Sign-On (SSO) users

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.

3.3.1. Key considerations

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.

Additional resources

Refer to Ansible Automation Platform 2.4 to 2.5. Linking accounts post upgrade, and Setting up SAML authentication for a demonstration of the post upgrade steps.

3.4. Migrating LDAP users

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

3.4.1. Key considerations

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.

3.4.2. Legacy user login and account linking

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.

3.4.3. Migrating LDAP users without account linking

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

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, 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, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
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.

© 2024 Red Hat, Inc.