Migrating from AWX 24 to Ansible Automation Platform 2.5

In the previous parts of the series, we discussed how to manage existing Red Hat Ansible Automation Platform with configuration as code from start to finish using configify.aapconfig collection.

However, you can also use the collection for different kinds of migrations. In this article, we will discuss migration from AWX 24 to Ansible Automation Platform 2.5.

Follow this series:

• Part 1: The first steps on the path of managing an existing Ansible Automation Platform instance as CaC, setting up Ansible Automation Platform accounts, collections, credentials, projects, and job templates required to run the automation, exporting configuration of some objects, handling secrets and special strings in the CaC, and managing configuration drift.
• Part 2: Completing the transition: exporting all objects, formatting configurations for readability, verification, access restrictions, and Git management.
• Part 3: Migrating configurations from AWX 24 to Ansible Automation Platform 2.5.
• Part 4: Migrating smart inventories (deprecated in future Ansible Automation Platform releases) to constructed inventories.
• Part 5: Migrating configurations from Ansible Automation Platform 2.4 to Ansible Automation Platform 2.5.

Preparation and planning

While there is a path to perform in-place migration from AWX to Ansible Automation Platform, there are cases when it’s not possible or simply preferable to do export/import instead. An example is migration to one of Red Hat’s Ansible Automation Platform cloud offerings which don’t allow restoring a backup taken from an on-prem instance.

For the purposes of this article, we assume the following:

• You are running an instance of AWX 24.
• You have deployed Ansible Automation Platform version 2.5 as a separate instance.
• Galaxy configuration will not be migrated, Ansible Automation Platform Hub will need to be configured from scratch.

Planning and preparation for configuration export is the same no matter if export is being done to manage an existing instance or migrate to another one. The steps are described in detail in the two previous articles. Let’s do a brief recap of what to do:

1. Make sure all required Red Hat certified collections are available in local Galaxy and Hub. For disconnected environments all collections need to be available locally.
2. Create required tokens and configurations as described in the first article. This time, you need to do the steps twice: in source cluster (AWX) and in destination cluster (AAP). The configurations include:
   • API tokens for Controller (AWX) and Gateway (AAP)
   • API token for Hub (AAP)
   • Credential types for Hub credentials
   • Credentials for Controller, Hub (AAP), and Gateway (AAP)
   • Empty inventories
   • Git projects
   • Job templates
3. Decide how to handle secrets and prepare required configurations as described in the "Handling objects with secrets" section of Part 1.
4. Run configify.aapconfig.aap_audit_problematic_objects.yml, fix problematic objects, and perform optional cleanup as discussed in the "Pre-export steps" section of Part 2.

You should give separate consideration to external users authenticating via SSO. These users are added to the cluster during first login, but they will not be exported together with local users. If you are assigning permissions to specific external users, which is not a recommended practice, then you will need to delay importing roles related to these users until they log in. This may be another pre-migration cleanup task, switching these roles to teams instead.

Exporting configuration

Configuration export is the same as described in Part 2. Create and run the following playbook against the AWX instance:

---
- name: Run playbook to export AAP configurations
  import_playbook: configify.aapconfig.aap_audit_all.yml

This time, because we are exporting from AWX, we need to specify:

aap_platform: awx24

This switch tells the playbook to expect data returned by API calls to be specific to AWX, which in some cases is slightly different from what is returned by Ansible Automation Platform. In addition, it skips parsing configurations available only in Ansible Automation Platform 2.5.

Because we will be importing to Ansible Automation Platform 2.5, we need to run the playbook with:

format_for_25: true

This makes sure certain configurations such as roles and authenticators are formatted for import into Ansible Automation Platform 2.5. You can find more details on the differences in Part 5 of this series.

Once exported let’s go through the formatting procedure described in the "Formatting the output" section of Part 2.

Importing configuration

The import process is also the same as described in Part 2. However this time you need to run the playbook against the following new Ansible Automation Platform cluster:

  tasks:
    - name: Include variables
      ansible.builtin.include_vars: all_aap_objects
      tags: always
- name: Run playbook to apply AAP configurations
  import_playbook: configify.aapconfig.aap_configure.yml

In this case, running import in check mode is not necessary since there is no existing configuration. For the same reason we can run import playbook using controller_config_all_apply tag, which only applies configurations without checking existing objects and configuration drift.

After you've completed the import, don’t forget to include objects created in the new cluster during preparation steps into the CaC: credential type, credentials, project and job template. You can export these using specific tags as follows:

export_credential_types
export_credentials
export_projects
export_templates

Then merge into the existing CaC.

Final thoughts

As we can see with the configify.aapconfig collection, you don't need to import and export from/to the same cluster. Different parameters allow for flexibility to import/export between different versions of the platform. Stay tuned for the next two installments where we will discuss more migration scenarios.