Migration prerequisites

Prerequisites for migrating your Ansible Automation Platform deployment. For your specific migration path, ensure that you meet all necessary conditions before proceeding.

Warning:
To upgrade to Ansible Automation Platform 2.7, you must first migrate from your RPM-based deployment to a containerized or OpenShift Container Platform deployment. RPM-based deployments are not supported as an upgrade path to 2.7.

Prerequisites for migrating using the aap_snapshot collection

Before using the ansible.aap_snapshot collection to migrate your Ansible Automation Platform deployment to OpenShift Container Platform, verify that your environment meets the prerequisites for both phases of the migration.

Prerequisites are divided into two stages that correspond to the export and import phases of the workflow. Meet all export prerequisites before running the artifact_export playbook on your source environment. Meet all import prerequisites before running the artifact_import playbook on your control node.

RPM version requirements for the aap_snapshot collection

The ansible.aap_snapshot collection is version-locked and can only migrate between matching Ansible Automation Platform versions. If your source deployment is RPM 2.4 on RHEL 8, you must first upgrade to RPM 2.6 on RHEL 9 before using the collection.

A 2.4 source cannot produce a migration artifact compatible with a 2.6 OpenShift Container Platform target. The upgrade involves four steps:

  1. Back up your RPM 2.4 deployment on RHEL 8.
  2. Install Ansible Automation Platform 2.4 on new RHEL 9 hosts.
  3. Restore the RPM 2.4 backup using the installation program's built-in restore mechanism. New RHEL 9 hosts are required because the backup cannot be restored to existing RHEL 8 hosts.
  4. Upgrade from RPM 2.4 to 2.6 on the RHEL 9 hosts.

This migration path does not cover disconnected environments or components that the migration collection excludes. For the complete list, see Out of scope.

Prerequisites for RPM-based deployment export

Before running the artifact_export playbook, verify that your source RPM deployment, control node, and network connectivity meet all prerequisites. The playbook includes an automated preflight role that validates services and database connectivity at runtime.

For an overview of available migration paths from RPM 2.4 on RHEL 8, see Plan your migration from RPM-based to operator-managed Ansible Automation Platform.

Source environment

  • Your Ansible Automation Platform deployment is version 2.6, installed using the RPM installer on Red Hat Enterprise Linux 9.

    Note:

    If your deployment is Ansible Automation Platform 2.4 on Red Hat Enterprise Linux 8, you must upgrade to 2.6 on Red Hat Enterprise Linux 9 before running the export. For more information, see RPM version requirements for the aap_snapshot collection.

  • At least one host is defined for the gateway component in the inventory. The playbook fails if no gateway hosts are found.

Control node

  • Ansible Core 2.16.0 or later is installed.

  • The ansible.aap_snapshot collection is installed from automation hub:

    ansible-galaxy collection install ansible.aap_snapshot

Connectivity

  • SSH access is available from the control node to all component hosts (automation controller, automation hub, platform gateway, Event-Driven Ansible, and database hosts). Disconnected environments are not supported.
  • become privileges are available on all component hosts.

Storage

  • The control node has sufficient free disk space at artifact_dir. The required disk space depends on component database sizes and, if automation hub content export is enabled, the size of the Pulp data directory (/var/lib/pulp/media/ on the automation hub host).

Prerequisites for the OCP deployment import

Before running the artifact_import playbook, verify that your control node, OpenShift cluster, and migration artifact are correctly configured. Meeting these requirements before you start prevents mid-run failures that require manual recovery.

Control node requirements

Ansible Core version
Ansible Core 2.16.0 or later is installed.
Collection installation

The ansible.aap_snapshot collection is installed from automation hub:

ansible-galaxy collection install ansible.aap_snapshot
Migration artifact
The .tar artifact from the export workflow is present on the control node and readable by the user running the playbook. Pass its full path using artifact_file. This variable has no default and the playbook fails at startup if it is not set.

OCP environment requirements

OpenShift cluster readiness
An OpenShift Container Platform cluster is provisioned and the Ansible Automation Platform Operator is installed in the target namespace. If the team responsible for your OpenShift environment is separate from the team managing Ansible Automation Platform, coordinate cluster access and namespace provisioning before beginning the import.
Kubeconfig access

A valid kubeconfig file with cluster-admin or namespace-admin access to the OpenShift Container Platform target namespace is available. The playbook resolves kubeconfig in this order:

  1. The kubeconfig extra variable (-e kubeconfig=/path/to/kubeconfig)
  2. The K8S_AUTH_KUBECONFIG environment variable
  3. The KUBECONFIG environment variable
  4. The default location (~/.kube/config)

The Ansible Automation Platform Operator uses the aap.ansible.com/v1alpha1 API version for all custom resources (AnsibleAutomationPlatform, AnsibleAutomationPlatformBackup, AnsibleAutomationPlatformRestore).

ReadWriteMany StorageClass for automation hub
A ReadWriteMany (RWX) StorageClass is available in the OpenShift Container Platform cluster, and hub_file_storage_class is set to its name. This is required when the artifact includes automation hub. Storage class auto-detection is not supported. If hub_file_storage_class is not set and the artifact includes automation hub, the import fails at preflight.
Platform gateway admin password and hostname
gateway_admin_password and gateway_hostname are set in your inventory. Both are required for the Pulp repair API call during hub reconciliation. The reconcile hub role runs for all OpenShift Container Platform imports regardless of whether the artifact includes automation hub, so these variables are required even if hub was not exported.
Version match
The Ansible Automation Platform version in the artifact matches the version installed in the OpenShift Container Platform target namespace, and the operator deployment is healthy.
Network access
The control node has network access to the OpenShift Container Platform API endpoint on port 6443.

RPM to containerized migration prerequisites

Before migrating from an RPM-based deployment to a container-based deployment, ensure you meet the following prerequisites:

Note:
Completing this migration is a required step if you plan to upgrade to Ansible Automation Platform 2.7. RPM-based deployments are not supported as an upgrade path to 2.7.
  • You have a source RPM-based deployment of Ansible Automation Platform.
  • The source RPM-based deployment is on the latest async release of the version you are on.
  • You have a target environment prepared for a container-based deployment of Ansible Automation Platform.
  • You have downloaded the containerized installation program for the latest release of the Ansible Automation Platform version you are on.
  • You have enough storage for database dumps and backups.
  • There is network connectivity between the source and target environments.
Important:

Before completing this migration, see How do I migrate Ansible Automation Platform 2.6 from an RPM to a containerized installation? on the Red Hat Customer Portal for the migration procedures.

RPM to OpenShift Container Platform migration prerequisites

Before migrating from an RPM-based deployment to an OpenShift Container Platform deployment, ensure you meet the following prerequisites.

Note:

Completing this migration is a required step if you plan to upgrade to Ansible Automation Platform 2.7. RPM-based deployments are not supported as an upgrade path to 2.7.

If your source deployment is Ansible Automation Platform RPM 2.4 on RHEL 8, you must first upgrade to RPM 2.6 on RHEL 9 before migrating.

  • You have a source RPM-based deployment of Ansible Automation Platform 2.6 on RHEL 9.
  • The source RPM-based deployment is on the latest async release of the version you are on.
  • You have a target OpenShift Container Platform environment ready.
  • You have Ansible Automation Platform Operator available for the latest release of the Ansible Automation Platform version you are on.
  • You have made a decision on internal or external database configuration.
  • You have made a decision on internal or external Redis configuration.
  • There is network connectivity between the source and target environments.

RPM to Managed Ansible Automation Platform migration prerequisites

Before migrating from an RPM-based deployment to a Managed Ansible Automation Platform deployment, ensure you meet the following prerequisites:

Note:
Completing this migration is a required step if you plan to upgrade to Ansible Automation Platform 2.7. RPM-based deployments are not supported as an upgrade path to 2.7.
  • You have a source RPM-based deployment of Ansible Automation Platform.
  • The source deployment must be on the same major version as the Managed Ansible Automation Platform offering, and must be on the latest async/patch release of that version.
    • Determine the Managed AAP version: Check the 2.7 Release Notes or contact Red Hat Support to confirm the current version deployed in Managed Ansible Automation Platform.
    • Upgrade your source if needed: If your source is on an older major version (e.g., 2.4 or 2.5), you must upgrade to match the Managed Ansible Automation Platform version, for example, 2.7, before migrating.
    • Apply the latest patches: Ensure your source is on the latest async/patch release, for example, 2.7.3, not 2.7.0.
    • Why this matters: Migration uses a database dump-and-restore process that requires version parity. Cross-version migrations are not supported.
  • You have a target Managed Ansible Automation Platform deployment.
  • You have enabled local authentication on the source deployment before the migration.
  • A local administrator account must be functional on the source deployment before migration. Verify this by performing a successful login to the source deployment.
  • You have a plan to retain a backup throughout the migration process and to ensure that your existing Ansible Automation Platform deployment remains active until your migration has completed successfully.
  • You have a plan for any environment changes based on the migration from a self-hosted Ansible Automation Platform deployment to a Managed Ansible Automation Platform deployment:
    • Job log retention changes from a customer-configured option to 30 days.
    • Network changes occur when moving the control plane to the managed service.
    • Automation mesh requires reconfiguration.
  • You must reconfigure or re-create Single Sign-On (SSO) identity providers post-migration to account for URL changes.

Containerized to OpenShift Container Platform migration prerequisites

Before migrating from a container-based deployment to an OpenShift Container Platform deployment, ensure that you meet the following prerequisites:

  • You have a source container-based deployment of Ansible Automation Platform.
  • The source deployment is on the latest async release of the version you are on.
  • You have a target OpenShift Container Platform environment ready.
  • You have an Ansible Automation Platform Operator available for the latest release of the Ansible Automation Platform version you are on.
  • You have decided between internal or external database configuration.
  • You have decided between internal or external Redis configuration.
  • There is network connectivity between the source and target environments.

Containerized to Managed Ansible Automation Platform migration prerequisites

Before migrating from a container-based deployment to a Managed Ansible Automation Platform deployment, ensure that you meet the following prerequisites:

  • You have a source container-based deployment of Ansible Automation Platform.
  • The source deployment is on the latest release of the Ansible Automation Platform version you are on.
  • You have a target Managed Ansible Automation Platform deployment.
  • You have enabled local authentication on the source deployment before the migration.
  • A local administrator account must be functional on the source deployment before migration. Verify this by performing a successful login to the source deployment.
  • You have a plan to retain a backup throughout the migration process and to ensure that your existing Ansible Automation Platform deployment remains active until your migration has completed successfully.
  • You have a plan for any environment changes based on the migration from a self-hosted Ansible Automation Platform deployment to a Managed Ansible Automation Platform deployment:
    • Job log retention changes from a customer-configured option to 30 days.
    • Network changes occur when moving the control plane to the managed service.
    • Automation mesh requires reconfiguration.
  • You must reconfigure or re-create Single Sign-On (SSO) identity providers post-migration to account for URL changes.