Chapter 6. Source environment

Procedure

1. Document the full topology of your current RPM deployment:

   1. Map out all servers, nodes, and their roles (for example control nodes, execution nodes, database servers).
   2. Note the hostname, IP address, and function of each server in your deployment.
   3. Document the network configuration between components.

2. Ansible Automation Platform version information:

   1. Record the exact Ansible Automation Platform version (X.Y) currently deployed.

3. Document the specific version of each component:

   1. Automation controller version
   2. Automation hub version
   3. Platform gateway version

4. Database configuration:

   1. Database names for each component
   2. Database users and roles
   3. Connection parameters and authentication methods
   4. Any custom PostgreSQL configurations or optimizations

Procedure

1. Verify the PostgreSQL database version is PostgreSQL version 15.

   You can verify your current PostgreSQL version by connecting to your database server and running the following command as the postgres user:

   $ psql -c 'SELECT version();'

   Copy to Clipboard Toggle word wrap
   Important

   PostgreSQL version 15 is a strict requirement for the migration process to succeed. If running PostgreSQL 13 or earlier, upgrade to version 15 before proceeding with the migration.

   If using an Ansible Automation Platform managed database, re-run the installation program to upgrade the PostgreSQL version. If using a customer provided (external) database, contact your database administrator or service provider to confirm the version and arrange for an upgrade if required.

2. Create a complete backup of the source environment:

   $ ./setup.sh -e 'backup_dest=/path/to/backup_dir/' -b

   Copy to Clipboard Toggle word wrap

3. Get the connection settings from one node from each of the component groups.

   For each command, access the host and become the root user.

   • Access the automation controller node and run:

     # awx-manage print_settings | grep '^DATABASES'

     Copy to Clipboard Toggle word wrap

   • Access the automation hub node and run:

     # grep '^DATABASES' /etc/pulp/settings.py

     Copy to Clipboard Toggle word wrap

   • Access the platform gateway node and run:

     # aap-gateway-manage print_settings | grep '^DATABASES'

     Copy to Clipboard Toggle word wrap

4. Stage the manually created artifact on the platform gateway node.

   # mkdir -p /tmp/backups/artifact/{controller,gateway,hub}

   Copy to Clipboard Toggle word wrap

   # mkdir -p /tmp/backups/artifact/controller/custom_configs

   Copy to Clipboard Toggle word wrap

   # touch /tmp/backups/artifact/secrets.yml

   Copy to Clipboard Toggle word wrap

   # cd /tmp/backups/artifact/

   Copy to Clipboard Toggle word wrap

5. Validate the database size and make sure you have enough space on the filesystem for the pg_dump.

   You can verify the database sizes by connecting to your database server and running the following command as the postgres user:

   $ psql -c '\l+'

   Copy to Clipboard Toggle word wrap

   Adjust the filesystem size or mount an external filesystem as needed before performing the next step.

   Note

   This procedure assumes that all target files will be sent to the /tmp filesystem. You must adjust the commands to match your environment’s needs.

6. Perform database dumps of all components on the platform gateway node within the artifact you created.

   # psql -h <pg_hostname> -U <component_pg_user> -d <database_name> -t -c 'SHOW server_version;' # ensure connectivity to the database

   Copy to Clipboard Toggle word wrap

   # pg_dump -h <pg_hostname> -U <component_pg_user> -d <component_pg_name> --clean --create -Fc -f <component>/<component>.pgc

   Copy to Clipboard Toggle word wrap

   # ls -ld <component>/<component>.pgc

   Copy to Clipboard Toggle word wrap

   # echo "<component>_pg_database: <database_name>" >> secrets.yml ## Add the database name for the component to the secrets file

   Copy to Clipboard Toggle word wrap

7. Export secrets from the RPM environment from one node of each component group.

   For each of the following steps, use the root user to run the commands.

   • Access the automation controller node, gather the secret key, and add it to the controller_secret_key value in the secrets.yml file.

     # cat /etc/tower/SECRET_KEY

     Copy to Clipboard Toggle word wrap

   • Access the automation hub node, gather the secret key, and add it to the hub_secret_key value in the secrets.yml file.

     # grep '^SECRET_KEY' /etc/pulp/settings.py | awk -F'=' '{ print $2 }'

     Copy to Clipboard Toggle word wrap

   • Access the automation hub node, gather the database_fields.symmetric.key value, and add it to the hub_db_fields_encryption_key value in the secrets.yml file.

     # cat /etc/pulp/certs/database_fields.symmetric.key

     Copy to Clipboard Toggle word wrap

   • Access the platform gateway node, gather the secret key, and add it to the gateway_secret_key value in the secrets.yml file.

     # cat /etc/ansible-automation-platform/gateway/SECRET_KEY

     Copy to Clipboard Toggle word wrap

8. Export automation controller custom configurations.

   If any custom settings exist on the /etc/tower/conf.d, copy them to /tmp/backups/artifact/controller/custom_configs.

   Configuration files on automation controller that are managed by the installation program and not considered custom:

   • /etc/tower/conf.d/postgres.py
   • /etc/tower/conf.d/channels.py
   • /etc/tower/conf.d/caching.py
   • /etc/tower/conf.d/cluster_host_id.py

9. Package the artifact.

   # cd /tmp/backups/artifact/

   Copy to Clipboard Toggle word wrap

   # [ -f sha256sum.txt ] && rm -f sha256sum.txt; find . -type f -name "*.pgc" -exec sha256sum {} \; >> sha256sum.txt

   Copy to Clipboard Toggle word wrap

   # cat sha256sum.txt

   Copy to Clipboard Toggle word wrap

   # cd ..

   Copy to Clipboard Toggle word wrap

   # tar cf artifact.tar artifact

   Copy to Clipboard Toggle word wrap

   # sha256sum artifact.tar > artifact.tar.sha256

   Copy to Clipboard Toggle word wrap

   # sha256sum --check artifact.tar.sha256

   Copy to Clipboard Toggle word wrap

   # tar tvf artifact.tar

   Copy to Clipboard Toggle word wrap

   Example output of tar tvf artifact.tar:

   drwxr-xr-x ansible/ansible     0 2025-05-08 16:48 artifact/
   drwxr-xr-x ansible/ansible     0 2025-05-08 16:33 artifact/controller/
   -rw-r--r-- ansible/ansible 732615 2025-05-08 16:26 artifact/controller/controller.pgc
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:33 artifact/controller/custom_configs/
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:11 artifact/gateway/
   -rw-r--r-- ansible/ansible 231155 2025-05-08 16:28 artifact/gateway/gateway.pgc
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:26 artifact/hub/
   -rw-r--r-- ansible/ansible 29252002 2025-05-08 16:26 artifact/hub/hub.pgc
   -rw-r--r-- ansible/ansible      614 2025-05-08 16:24 artifact/secrets.yml
   -rw-r--r-- ansible/ansible      338 2025-05-08 16:48 artifact/sha256sum.txt

   Copy to Clipboard Toggle word wrap
10. Download the artifact.tar and artifact.tar.sha256 to your local machine or transfer to the target node with the scp command.

Procedure

1. Document the full topology of your current containerized deployment:

   1. Map out all servers, nodes, and their roles (for example control nodes, execution nodes, database servers).
   2. Note the hostname, IP address, and function of each server in your deployment.
   3. Document the network configuration between components.

2. Ansible Automation Platform version information:

   1. Record the exact Ansible Automation Platform version (X.Y) currently deployed.

3. Document the specific version of each component:

   1. Automation controller version
   2. Automation hub version
   3. Platform gateway version

4. Database configuration:

   1. Database names for each component
   2. Database users and roles
   3. Connection parameters and authentication methods
   4. Any custom PostgreSQL configurations or optimizations
5. Identify all custom configurations and settings
6. Document container resource allocations and volumes

Procedure

1. Verify the PostgreSQL database version is PostgreSQL version 15.

   You can verify your current PostgreSQL version by connecting to your database server and running the following command as the postgres user:

   $ podman exec -it postgresql bash -c 'psql -c "SELECT version();"'

   Copy to Clipboard Toggle word wrap
   Important

   PostgreSQL version 15 is a strict requirement for the migration process to succeed. If running PostgreSQL 13 or earlier, upgrade to version 15 before proceeding with the migration.

   If using an Ansible Automation Platform managed database, re-run the installation program to upgrade the PostgreSQL version. If using a customer provided (external) database, contact your database administrator or service provider to confirm the version and arrange for an upgrade if required.

2. Create a complete backup of the source environment:

   $ ansible-playbook -i <path_to_inventory> ansible.containerized_installer.backup

   Copy to Clipboard Toggle word wrap

3. Get the connection settings from one node in each of the component groups.

   • Access the automation controller node and run:

     $ podman exec -it automation-controller-task bash -c 'awx-manage print_settings | grep '^DATABASES'

     Copy to Clipboard Toggle word wrap

   • Access the automation hub node and run:

     $ podman exec -it automation-hub-api bash -c "pulpcore-manager diffsettings | grep '^DATABASES'"

     Copy to Clipboard Toggle word wrap

   • Access the platform gateway node and run:

     $ podman exec -it automation-gateway bash -c "aap-gateway-manage print_settings | grep '^DATABASES'"

     Copy to Clipboard Toggle word wrap

4. Validate the database size and make sure you have enough space on the filesystem for the pg_dump.

   You can verify the database sizes by connecting to your database server and running the following command as the postgres user:

   $ podman exec -it postgresql bash -c 'psql -c "\l+"'

   Copy to Clipboard Toggle word wrap

   Adjust the filesystem size or mount an external filesystem as needed before performing the next step.

   Note

   This procedure assumes that all target files will be sent to the /tmp filesystem. You might want to adjust the commands to match your environment’s needs.

5. Stage the manually created artifact on the platform gateway node.

   # mkdir -p /tmp/backups/artifact/{controller,gateway,hub}

   Copy to Clipboard Toggle word wrap

   # mkdir -p /tmp/backups/artifact/controller/custom_configs

   Copy to Clipboard Toggle word wrap

   # touch /tmp/backups/artifact/secrets.yml

   Copy to Clipboard Toggle word wrap

   # cd /tmp/backups/artifact/

   Copy to Clipboard Toggle word wrap

6. Perform database dumps of all components on the platform gateway node within the artifact created previously.

   To run the psql and pg_restore commands, you must create a temporary container and run the commands inside of it. This command must be run from the database node.

   $ podman run -it --rm --name postgresql_restore_temp --network host --volume ~/aap/tls/extracted:/etc/pki/ca-trust/extracted:z --volume ~/aap/postgresql/server.crt:/var/lib/pgsql/server.crt:ro,z --volume ~/aap/postgresql/server.key:/var/lib/pgsql/server.key:ro,z --volume /tmp/backups/artifact:/var/lib/pgsql/backups:ro,z registry.redhat.io/rhel8/postgresql-15:latest bash

   Copy to Clipboard Toggle word wrap
   Note

   This command assumes the image registry.redhat.io/rhel8/postgresql-15:latest. If you are missing the image, check the available images for the user with podman images ls.

   The command above opens a shell inside the container named postgresql_restore_temp and has the artifact mounted into /var/lib/pgsql/backups. Also, this command is mounting the PostgreSQL certificates to ensure that you can resolve the correct certificates.

   bash-4.4$ cd /var/lib/pgsql/backups
   bash-4.4$ psql -h <pg_hostname> -U <component_pg_user> -d <database_name> -t -c 'SHOW server_version;' # ensure connectivity to db
   bash-4.4$ pg_dump -h <pg_hostname> -U <component_pg_user> -d <component_pg_name> --clean --create -Fc -f <component>/<component>.pgc
   bash-4.4$ ls -ld <component>/<component>.pgc
   bash-4.4$ echo "<component>_pg_database: <database_name>" >> secrets.yml ## Add the DB name for the component to the secrets file

   Copy to Clipboard Toggle word wrap

   After collecting this data, exit from this temporary container.

7. Export the secrets from the containerized environment from one node of each component group.

   For each step below, use the root user to run the commands.

   1. Access the automation controller node and gather the secret key and add to the controller_secret_key value in secrets.yaml file.

      $ podman secret inspect --showsecret --format "{{.SecretData}}" controller_secret_key

      Copy to Clipboard Toggle word wrap

   2. Access the automation hub node and gather the secret key and add to the hub_secret_key value in secrets.yaml file.

      $ podman secret inspect --showsecret --format "{{.SecretData}}" hub_secret_key

      Copy to Clipboard Toggle word wrap

   3. Access the automation hub node and gather the database_fields.symmetric.key value and add to the hub_db_fields_encryption_key value in secrets.yaml file.

      $ podman secret inspect --showsecret --format "{{.SecretData}}" hub_database_fields

      Copy to Clipboard Toggle word wrap

   4. Access the platform gateway node and gather the secret key and add to the gateway_secret_key value in secrets.yaml file.

      $ podman secret inspect --showsecret --format "{{.SecretData}}" gateway_secret_key

      Copy to Clipboard Toggle word wrap

8. Export automation controller custom configurations.

   If any extra_settings exist in your containerized installation inventory, copy them into a new file and saving them under /tmp/backups/artifact/controller/custom_configs.

9. Package the artifact.

   # cd /tmp/backups/artifact/
   # [ -f sha256sum.txt ] && rm -f sha256sum.txt; find . -type f -name "*.pgc" -exec sha256sum {} \; >> sha256sum.txt
   # cat sha256sum.txt
   # cd ..
   # tar cf artifact.tar artifact
   # sha256sum artifact.tar > artifact.tar.sha256
   # sha256sum --check artifact.tar.sha256
   # tar tvf artifact.tar

   Copy to Clipboard Toggle word wrap

   Example output of tar tvf artifact.tar:

   drwxr-xr-x ansible/ansible     0 2025-05-08 16:48 artifact/
   drwxr-xr-x ansible/ansible     0 2025-05-08 16:33 artifact/controller/
   -rw-r--r-- ansible/ansible 732615 2025-05-08 16:26 artifact/controller/controller.pgc
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:33 artifact/controller/custom_configs/
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:11 artifact/gateway/
   -rw-r--r-- ansible/ansible 231155 2025-05-08 16:28 artifact/gateway/gateway.pgc
   drwxr-xr-x ansible/ansible      0 2025-05-08 16:26 artifact/hub/
   -rw-r--r-- ansible/ansible 29252002 2025-05-08 16:26 artifact/hub/hub.pgc
   -rw-r--r-- ansible/ansible      614 2025-05-08 16:24 artifact/secrets.yml
   -rw-r--r-- ansible/ansible      338 2025-05-08 16:48 artifact/sha256sum.txt

   Copy to Clipboard Toggle word wrap
10. Download the artifact.tar and artifact.tar.sha256 to your local machine or transfer to the target node with the scp command.