.. bqg1571264986191 .. _running-ansible-backup-playbook-locally-on-the-controller: ===================================================== 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 |prod| configuration, data, and user container images in registry.local: **Optimized**: Optmized restore must be used on |AIO-SX|. .. code-block:: none ~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml -e "ansible_become_pass= admin_password=" -e "backup_registry_filesystem=true" **Legacy**: Legacy restore must be used on systems that are not |AIO-SX|. .. code-block:: none ~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/backup.yml -e "ansible_become_pass= admin_password=" -e "backup_user_images=true" **Example using overrides encrypted with Ansible Vault**: .. code-block:: none ~(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 ``_user_images_backup_.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 ``_image_registry_backup_.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. ``-e exclude_sw_deployments={true,false}`` To exclude software deployment data from being included. When set to true, software deployments are not included in the backup. By default, this is true for |AIO-SX| and subclouds and false for |AIO-DX| systems (except subclouds). The backup will always include software deployment metadata. .. 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=`` 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. ``-e ignore_kube_version_check_for_backup=true`` To enable backups with older versions of Kubernetes. 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 software deployment data can save a significant amount of storage space, transfer time, and compress/decompress computation. .. warning:: Directories should only be excluded for |AIO-SX| deployments when optimized Restore is used. The and 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 :command:`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 :command:`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`` .. code-block:: none ansible_become_pass: "" admin_password: "" backup_registry_filesystem: "true" exclude_dirs: /var/home/**,/var/home" backup_encryption_passphrase: "" ... 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: .. code-block:: none ~(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. .. _running-ansible-backup-playbook-locally-on-the-controller-ul-wj1-vxh-pmb: - 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. .. _running-ansible-backup-playbook-locally-on-the-controller-ul-rdp-gyh-pmb: - platform_backup_filename_prefix - openstack_backup_filename_prefix - docker_local_registry_backup_filename_prefix - dc_vault_backup_filename_prefix - openstack_app_name: "|prod-os|" (optional for |prod-os| 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: .. _running-ansible-backup-playbook-locally-on-the-controller-ul-p3b-f13-pmb: - 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.