Back up and restore your RPM deployment

Protecting your Ansible Automation Platform RPM deployment ensures that you can recover from system failures, data corruption, or configuration errors. Regular backups minimize downtime and protect your configurations and data.

Implementing backup and restore procedures helps you to:

  • Protect critical automation assets: Safeguard your data including configurations, inventory, credentials, and job history from unexpected failures or data loss.
  • Enable disaster recovery: Restore your environment quickly after hardware failures or other unexpected events to maintain business continuity.
  • Support testing and development: Create copies of your environment for testing upgrades or configuration changes without affecting production systems.

Backup and restore overview
Copy link

You can backup and restore your system by using the Ansible Automation Platform setup playbook.

Note

When backing up Ansible Automation Platform, use the installation program that matches your currently installed version of Ansible Automation Platform.

When restoring Ansible Automation Platform, use the latest installation program available at the time of the restore. For example, if you are restoring a backup taken from version 2.6-1, use the latest 2.6-x installation program available at the time of the restore.

Backup and restore functionality only works with the PostgreSQL versions supported by your current Ansible Automation Platform version. For more information, see System requirements in Planning your installation.

The Ansible Automation Platform setup playbook is invoked as setup.sh from the path where you unpacked the platform installer tar file. It uses the same inventory file used by the install playbook. The setup script takes the following arguments for backing up and restoring:

  • -b: Perform a database backup rather than an installation.
  • -r: Perform a database restore rather than an installation.

As the root user, call setup.sh with the appropriate parameters and the Ansible Automation Platform backup or restored as configured:

root@localhost:~# ./setup.sh -b
root@localhost:~# ./setup.sh -r

Backup files are created on the same path that setup.sh script exists. You can change it by specifying the following EXTRA_VARS:

root@localhost:~# ./setup.sh -e 'backup_dest=/path/to/backup_dir/' -b

A default restore path is used unless you provide EXTRA_VARS with a non-default path, as shown in the following example:

root@localhost:~# ./setup.sh -e 'restore_backup_file=/path/to/nondefault/backup.tar.gz' -r

Optionally, you can override the inventory file used by passing it as an argument to the setup script:

setup.sh -i <inventory file>

Backup and restore playbooks
Copy link

automation controller includes playbooks to backup and restore your installation.

In addition to the install.yml file included with your setup.sh setup playbook, there are also backup.yml and restore.yml files.

These playbooks serve to backup and restore.

  • The overall backup, backs up:
    • The database
    • The SECRET_KEY file
  • The per-system backups include:
    • Custom configuration files
    • Manual projects
  • The restore backup restores the backed up files and data to a freshly installed and working second instance of automation controller.

When restoring your system, installation program checks to see that the backup file exists before beginning the restoration. If the backup file is not available, your restoration fails.

Note

Make sure that your automation controller hosts are properly set up with SSH keys, user or pass variables in the hosts file, and that the user has sudo access.

Considerations for backup and restore
Copy link

Consider the following points when you backup and restore your system:

Disk space
Review your disk space requirements to ensure you have enough room to backup configuration files, keys, other relevant files, and the database of the Ansible Automation Platform installation.
System credentials

Confirm you have the required system credentials when working with a local database or a remote database. On local systems, you might need root or sudo access, depending on how credentials are set up. On remote systems, you might need different credentials to grant you access to the remote system you are trying to backup or restore.

Note

The Ansible Automation Platform database backups are staged on each node at /var/backups/automation-platform through the variable backup_dir. You might need to mount a new volume to /var/backups or change the staging location with the variable backup_dir to prevent issues with disk space before running the ./setup.sh -b script.
Version
You must always use the most recent minor version of a release to backup or restore your Ansible Automation Platform installation version. For example, if the current platform version you are on is 2.0.x, only use the latest 2.0 installer.
File path
When using setup.sh to do a restore from the default restore file path, /var/lib/awx, -r is still required to do the restore, but it no longer accepts an argument. If a non-default restore file path is needed, you must provide this as an extra_var (root@localhost:~# ./setup.sh -e 'restore_backup_file=/path/to/nondefault/backup.tar.gz' -r).
Directory
If the backup file is placed in the same directory as the setup.sh installer, the restore playbook automatically locates the restore files. In this case, you do not need to use the restore_backup_file extra var to specify the location of the backup file.

Back up your Ansible Automation Platform instance
Copy link

Back up an Ansible Automation Platform instance by running the setup.sh script with the backup_dest flag. You can also enable the compression flags use_archive_compression and use_db_compression to reduce the size of the backup artifacts.

Procedure
Copy link

  1. Navigate to your Ansible Automation Platform installation directory.
  2. Run the ./setup.sh script following the example below: 
    $ ./setup.sh -e 'backup_dest=/ansible/mybackup' -e
'use_archive_compression=true' 'use_db_compression=true @credentials.yml -b

    Where:

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

Results
Copy link

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

Backup and restore in clustered environments
Copy link

Learn how to back up and restore automation controller in a clustered environment.

The procedure for backup and restore for a clustered environment is similar to a single install, except for some of the following considerations:

  • If restoring to a new cluster, ensure that the old cluster is shut down before proceeding because they can conflict with each other when accessing the database.
  • Per-node backups are only restored to nodes bearing the same hostname as the backup.
  • When restoring to an existing cluster, the restore has the following:
    • A dump of the PostgreSQL database
    • UI artifacts, included in the database dump
    • An automation controller configuration (retrieved from /etc/tower)
    • An automation controller secret key
    • Manual projects

Restore to a different cluster
Copy link

When restoring a backup to a separate instance or cluster, manual projects and custom settings under /etc/tower are retained. Job output and job events are stored in the database, and therefore, not affected.

The restore process does not alter instance groups present before the restore. It does not introduce any new instance groups either. Restored automation controller resources that were associated to instance groups likely need to be reassigned to instance groups present on the new automation controller cluster.

Warning

If you plan to use a backup and restore operation to migrate your Ansible Automation Platform instance to a different cluster or new set of hostnames, any Red Hat Ansible Automation Platform credentials you set up for Event-Driven Ansible controller will break, causing your rulebook activations to fail. You must manually edit and update the automation controller URL and associated credentials after the restore operation is complete to restore connectivity.