Ansible Automation Platform Upgrade Guide: Migration Path from AAP 2.4 and 2.5 to 2.6

Planning an upgrade to Ansible Automation Platform 2.6? This guide covers the supported migration paths from AAP 2.4 and 2.5, including topology migration, enterprise authentication, and automated IAM migration.

Upgrade Path Comparison

| Feature | AAP 2.4 → 2.6 | AAP 2.5 → 2.6 | |---|---|---| | Direct upgrade path | ✅ Yes | ✅ Yes | | Topology migration | ✅ Yes | ✅ Yes | | Enterprise auth migration (SAML/LDAP/OIDC) | ✅ Yes | Already on platform gateway | | Automated IAM migration | ✅ Yes | Already on platform gateway |

\AAP 2.5 customers already have the platform gateway installed and do not need to plan for any transitions or data movement.*

See also: AAP 2.6 SSO Integration: LDAP, SAML, and OIDC Authentication

Understanding Each Migration Step

1. Direct Upgrade Path

A single, streamlined process to upgrade to AAP 2.6, reducing intermediate steps and complexity. • No need to upgrade to 2.5 first (from 2.4) • Single installer execution handles the complete upgrade • Database schema migrations are handled automatically

Important: Customers on RHEL 8 must first migrate to RHEL 9 to use the direct 2.4 → 2.6 upgrade path.

2. Supported Topology Migration

A documented "lift-and-shift" process to move your entire AAP instance — including jobs, data, and configurations — from an RPM install to containerized or OpenShift deployment.

Before (RPM-based):                    After (Containerized):
┌─────────────────────┐               ┌─────────────────────┐
│ RHEL 8/9 Host       │               │ RHEL 9 / OpenShift  │
│ ┌─────────────────┐ │               │ ┌─────────────────┐ │
│ │ Controller RPM  │ │  ──────────►  │ │ Controller Pod  │ │
│ │ Hub RPM         │ │  lift-and-    │ │ Hub Pod         │ │
│ │ EDA RPM         │ │  shift        │ │ EDA Pod         │ │
│ │ PostgreSQL      │ │               │ │ PostgreSQL      │ │
│ └─────────────────┘ │               │ └─────────────────┘ │
└─────────────────────┘               └─────────────────────┘

3. Enterprise Auth Migration (AAP 2.4 → 2.6 only)

Enterprise authenticator configurations are seamlessly migrated to the platform gateway: • SAML — Single Sign-On configurations • LDAP — Directory service bindings and group mappings • OIDC — OpenID Connect provider settings

This simplifies post-upgrade setup by eliminating manual re-authentication configuration.

AAP 2.5 note: If you're on 2.5, you already have the platform gateway with authentication configured — no migration needed.

4. Automated IAM Migration (AAP 2.4 → 2.6 only)

Users, teams, roles, and permissions are automatically migrated from the controller to the platform gateway, preserving: • RBAC model and role assignments • Team memberships • Administrative privileges • Organization structures

Pre-Upgrade Checklist

# 1. Verify current version
automation-controller-service version
# 2. Check RHEL version (must be RHEL 9+ for direct upgrade)
cat /etc/redhat-release
# 3. Backup database
pg_dump -U awx -h localhost awx > /backup/awx-pre-upgrade-$(date +%Y%m%d).sql
# 4. Backup configuration
tar czf /backup/aap-config-$(date +%Y%m%d).tar.gz \
  /etc/tower/ \
  /etc/ansible-automation-platform/ \
  /var/lib/awx/
# 5. Document current topology
ansible-controller-service list

See also: AAP 2.6 Migration from AWX: Complete Upgrade and Data Migration Guide

Upgrade Procedure

From AAP 2.4

# 1. Migrate to RHEL 9 if on RHEL 8
# (Required before AAP upgrade)
# 2. Download AAP 2.6 setup bundle
curl -O https://access.redhat.com/downloads/content/480/...
# 3. Extract
tar xvf ansible-automation-platform-setup-bundle-2.6*.tar.gz
cd ansible-automation-platform-setup-bundle-2.6*/
# 4. Update inventory with existing deployment details
vi inventory
# 5. Run the installer (handles all 4 migration steps)
sudo ./setup.sh

From AAP 2.5

# Simpler path — no auth/IAM migration needed
# 1. Download AAP 2.6 setup bundle
# 2. Extract and configure inventory
# 3. Run installer
sudo ./setup.sh
# Platform gateway already installed — only controller/hub/EDA upgraded

Post-Upgrade Verification

---
- name: Verify AAP 2.6 upgrade
  hosts: localhost
  connection: local
  tasks:
    - name: Check controller version
      ansible.builtin.uri:
        url: "https://aap.example.com/api/v2/ping/"
        user: "{{ vault_aap_admin }}"
        password: "{{ vault_aap_password }}"
        force_basic_auth: true
        validate_certs: true
      register: ping_result
- name: Display version
      ansible.builtin.debug:
        msg: "AAP version: {{ ping_result.json.version }}"
- name: Verify authentication
      ansible.builtin.uri:
        url: "https://aap.example.com/api/gateway/v1/me/"
        user: "{{ vault_aap_admin }}"
        password: "{{ vault_aap_password }}"
        force_basic_auth: true
      register: auth_check
- name: Confirm platform gateway active
      ansible.builtin.assert:
        that: auth_check.status == 200
        fail_msg: "Platform gateway authentication failed"
        success_msg: "Platform gateway authentication working"

See also: How to Upgrade from AAP 2.4 to AAP 2.6 — Step-by-Step Guide

FAQ

Can I upgrade directly from AAP 2.4 to 2.7?

Check the AAP 2.7 release notes (GA June 3, 2026) for supported upgrade paths. The 2.4 → 2.6 direct path was specifically documented; 2.4 → 2.7 may require going through 2.6 first.

What if I'm on RHEL 8?

You must migrate to RHEL 9 before upgrading AAP. RHEL 8 does not support the direct 2.4 → 2.6 upgrade path.

Will my job history be preserved?

Yes. The topology migration preserves all jobs, data, and configurations. Database records are migrated intact.

Do I need downtime for the upgrade?

Yes, plan for a maintenance window. The upgrade process requires stopping AAP services. Duration depends on database size and topology complexity.

What about custom execution environments?

Custom EEs are preserved during upgrade. However, verify compatibility with the new ansible-core version included in AAP 2.6.

Related Articles

• Red Hat Ansible Automation Platform 2.7: What's New • Red Hat Summit 2026 Highlights • Ansible Automation Platform Single Node