Run Ansible Backup Playbook Locally on the Controller

In this method the Ansible Backup playbook is run on the active controller.

Note

Ensure that all certificates are valid and not expiring soon prior to the backup. The certificates are not automatically renewed, you MUST renew the soon-to-expire certificates before the backup operation.

Warning

The restore cannot recover expired certificates.

Use one of the following commands to run the Ansible Backup playbook and back up the StarlingX configuration, data, and user container images in registry.local:

Optimized: Optmized restore must be used on AIO-SX.

~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml -e "ansible_become_pass=<sysadmin password> admin_password=<sysadmin password>" -e "backup_registry_filesystem=true"

Legacy: Legacy restore must be used on systems that are not AIO-SX.

~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml -e "ansible_become_pass=<sysadmin password> admin_password=<sysadmin password>" -e "backup_user_images=true"

Example using overrides encrypted with Ansible Vault:

~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml --ask-vault-pass -e "override_files_dir=$HOME/override_dir

Following are the -e command line options:

Legacy

-e backup_user_images=true

Used in conjunction with legacy restore. This will create a backup of custom user images. The file generated by this flag will be named according to the pattern <inventory_hostname>_user_images_backup_<timestamp>.tgz.

Optimized

-e backup_registry_filesystem=true

Used in conjunction with optimized restore. This will create a backup of registry.local. The file generated by this flag will be named according to the pattern <inventory_hostname>_image_registry_backup_<timestamp>.tgz.

Common

-e backup_dir=/opt/backups

Directory where the backups will be saved.

-e ignore_health=false

When set to true, the backup playbook is allowed to be run on an unhealthy system. This is needed in some extreme cases.

Warning

Restoring a backup from an unhealthy system will lead to undefined behavior and/or failure.

-e backup_encryption_enabled=false

When set to true, the platform backup file and Hashicorp Vault backup will be encrypted. When this option is true then backup_encryption_passphrase is also requierd. The platform backup file will have a “.gpg” extension when encrypted. The Hashicorp Vault snapshot is encrypted before it is written to disk, so that the backup file remains a tar file.

-e backup_encryption_passphrase=<encryption_password>

When backup_encryption_enabled is set to true, then the backup_encryption_passphrase option is also required.

Note

It is also recommended to put the backup_encryption_passphrase into ansible-vault.

-e backup_hc_vault=false

When set to true, the backup playbook will also backup the Hashicorp Vault application, if the application is applied in the system.

To exclude a directory and all the files in it like /var/home* you can use the optional parameter -e "exclude_dirs=/var/home/**,/var/home".

Note

A ‘glob’ pattern is required to use -e "exclude_dirs=/var/home/**,/var/home", in order to ensure there is sufficient free space in the required directories in any event.

Note

To exclude multiple files and directories, separate them with a comma.

Excluding patch data can save a significant amount of storage space, transfer time, and compress/decompress computation.

To exclude patch data from being included in the backup, you can use the parameter: -e exclude_dirs=/opt/patching/**/*.

Warning

Directories should only be excluded for AIO-SX deployments when optimized Restore is used.

The <admin_password> and <ansible_become_pass> need to be set correctly using the -e option on the command line, with an override file secured with ansible-vault (recommended).

For example, create your override file with the ansible-vault create $HOME/override_dir/secrets.yml command and copy the following lines into the file. You will be prompted for a password to protect/encrypt the file. Use the ansible-vault edit $HOME/override_dir/secrets.yml command if the file needs to be edited after it is created.

The following yaml names are allowed:

  • {{ override_files_dir }}/secrets.yml

  • {{ override_files_dir }}/{{ inventory_hostname }}_secrets.yml

  • {{ override_files_dir }}/site.yml

  • {{ override_files_dir }}/{{ inventory_hostname }}.yml

ansible_become_pass: "<admin_password>"
admin_password: "<admin_password>"
backup_registry_filesystem: "true"
exclude_dirs: /var/home/**,/var/home"
backup_encryption_passphrase: "<encryption_password>"
...
EOF

The extra var backup_registry_filesystem is an optional parameter and it is used to backup all images on the registry backup, generating a file named {inventory_hostname}_image_registry_backup_YYYY_MM_DD_HH_mm_ss.tgz. When not specified, the restore will download images from the upstream docker registry.

For example:

~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml -e "backup_registry_filesystem=true"

A list of possible output files, files created depend on backup options and system configuration.

  • inventory_hostname_platform_backup_timestamp.tgz

  • inventory_hostname_wr-openstack_backup_timestamp.tgz

  • inventory_hostname_user_images_backup_timestamp.tgz

  • inventory_hostname_dc_vault_backup_timestamp.tgz

  • inventory_hostname_image_registry_backup_timestamp.tgz

  • inventory_hostname_hc_vault_backup_timestamp.tgz

The output files’ prefixes can be overridden with the following variables using the -e option on the command line or by using an override file.

  • platform_backup_filename_prefix

  • openstack_backup_filename_prefix

  • docker_local_registry_backup_filename_prefix

  • dc_vault_backup_filename_prefix

  • openstack_app_name: “StarlingX OpenStack” (optional for StarlingX OpenStack application backup)

  • registry_filesystem_backup_filename_prefix

  • hc_vault_backup_filename_prefix

The generated backup tar files will be displayed in the following format, when custom prefixes are not specified, for example:

  • localhost_docker_local_registry_backup_2024_07_15_21_24_22.tgz

  • localhost_platform_backup_2024_07_15_21_24_22.tgz

  • localhost_openstack_backup_2024_07_15_21_24_22.tgz

  • localhost_dc_vault_backup_2024_07_15_21_24_22.tgz

  • localhost_image_registry_backup_2024_07_15_21_24_22.tgz

  • localhost_hc_vault_backup_2024_07_15_21_24_22.tgz

When encryption is enabled, the platform backup file will have a “.gpg” extension, for example, “localhost_platform_backup_2024_07_15_21_24_22.tgz.gpg”

These files are located by default in the /opt/backups directory on controller-0, and contains the complete system backup.

If the default location needs to be modified, the variable backup_dir can be overridden using the -e option on the command line or by using an override file.