564417258c
Remove comment from Greg that is already addressed. Change-Id: Ib5f0584fa41f8e556f6b89d8f48434bcadc5bd58 Signed-off-by: Elisamara Aoki Gonçalves <elisamaraaoki.goncalves@windriver.com>
277 lines
11 KiB
ReStructuredText
277 lines
11 KiB
ReStructuredText
|
|
.. rmy1571265233932
|
|
.. _running-restore-playbook-locally-on-the-controller:
|
|
|
|
==============================================
|
|
Run Restore Playbook Locally on the Controller
|
|
==============================================
|
|
|
|
To run restore on the controller, you need to upload the backup to the
|
|
active controller.
|
|
|
|
You can use an external storage device, for example, a USB drive. Use the
|
|
following commands to run the Ansible Restore playbook:
|
|
|
|
**Optimized**: Optmized restore must be used on |AIO-SX|.
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/restore_platform.yml -e "restore_mode=optimized initial_backup_dir=<location_of_tarball ansible_become_pass=<admin_password> admin_password=<admin_password backup_filename=<backup_filename> wipe_ceph_osds=<true/false> restore_registry_filesystem=true ssl_ca_certificate_file=<complete path>/<ssl_ca certificates file>"
|
|
|
|
**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/restore_platform.yml -e "initial_backup_dir=<location_of_tarball ansible_become_pass=<admin_password> admin_password=<admin_password backup_filename=<backup_filename> wipe_ceph_osds=<true/false> ssl_ca_certificate_file=<complete path>/<ssl_ca certificates file>"
|
|
|
|
Below you can find other ``-e`` command line options:
|
|
|
|
**Common**
|
|
|
|
``-e restore_mode=optimized``
|
|
Enable optimized restore mode
|
|
|
|
.. note::
|
|
|
|
Optimized restore is currently supported only on |AIO-SX| systems.
|
|
|
|
``-e "initial_backup_dir=/home/sysadmin"``
|
|
Where the backup tgz files are located on box.
|
|
|
|
``-e backup_filename=localhost_platform_backup.tgz``
|
|
The basename of the platform backup tgz. The full path will be a
|
|
combination ``{initial_backup_dir}/{backup_filename}``
|
|
|
|
``-e backup_encryption_enabled=false``
|
|
If ``backup encryption`` is selected during platform backup, then this option
|
|
is also required when you run the platform restore procedure. Select this
|
|
option if the platform backup archive file includes the '.gpg' extension.
|
|
|
|
``-e backup_encryption_passphrase=<encryption_password>``
|
|
When ``backup_encryption_enabled`` is set to true, then the
|
|
``backup_encryption_passphrase`` option is also required. Consider using
|
|
ansible-vault to store and specify passwords.
|
|
|
|
.. _running-restore-playbook-locally-on-the-controller-steps-usl-2c3-pmb:
|
|
|
|
(Optional): You can select one of the following restore modes:
|
|
|
|
- To keep the Ceph cluster data intact (false - default option), use the
|
|
following parameter, when passing the extra arguments to the Ansible
|
|
Restore playbook command:
|
|
|
|
.. code-block:: none
|
|
|
|
wipe_ceph_osds=false
|
|
|
|
|
|
To wipe the Ceph cluster entirely (true), where the Ceph cluster will need
|
|
to be recreated, or if the Ceph partition was previously wiped, such as
|
|
during a fresh install between backup and restore or during reinstall, use
|
|
the following parameter:
|
|
|
|
.. code-block:: none
|
|
|
|
wipe_ceph_osds=true
|
|
|
|
- To define a convenient place to store the backup files, defined by
|
|
``initial-backup_dir``, on the system (such as the home folder for
|
|
sysadmin, or /tmp, or even a mounted USB device), use the
|
|
``on_box_data=true/false`` parameter.
|
|
|
|
If this parameter is set to true, Ansible Restore playbook will look
|
|
for the backup file provided on the target server. The parameter
|
|
``initial_backup_dir`` can be ommited from the command line. In this
|
|
case, the backup file will be under ``/opt/platform-backup`` directory.
|
|
|
|
If this parameter is set to false, the Ansible Restore playbook will
|
|
look for backup file provided on the Ansible controller. In this
|
|
case, both the ``initial_backup_dir`` and ``backup_filename`` must be
|
|
specified in the command.
|
|
|
|
Example of a backup file in ``/home/sysadmin``:
|
|
|
|
.. code-block:: none
|
|
|
|
~(keystone_admin)]$ ansible-playbook /usr/share/ansible/stx-ansible/playbooks/restore_platform.yml -e "initial_backup_dir=/home/sysadmin ansible_become_pass=St8rlingXCloud* admin_password=St8rlingXCloud* backup_filename=localhost_platform_backup_2020_07_27_07_48_48.tgz wipe_ceph_osds=true"
|
|
|
|
.. note::
|
|
|
|
If the backup contains patches, Ansible Restore playbook will apply
|
|
the patches and prompt you to reboot the system. Then you will need
|
|
to re-run Ansible Restore playbook.
|
|
|
|
The flag ``wipe_ceph_osds=true`` is required for a restore in a new
|
|
hardware. For more details, see :ref:`node-replacement-for-aiominussx-using-optimized-backup-and-restore-6603c650c80d`.
|
|
|
|
|
|
- ``ssl_ca_certificate_file`` defines a single certificate that
|
|
contains all the ssl_ca certificates that will be installed during the
|
|
restore. It will replace
|
|
``/opt/platform/config/<software-version>/ca-cert.pem``, which is a
|
|
single file containing all the ssl_ca certificates installed in
|
|
the host when the backup was done. The certificate assigned to this
|
|
parameter must follow this same pattern.
|
|
|
|
.. note::
|
|
|
|
The ssl_ca certificates are not automatically renewed, you MUST renew
|
|
the soon-to-expire certificates before the backup operation. The expired
|
|
ssl_ca certificates are not restored.
|
|
For more details, see :ref: `Recommended Backup and Retention Policies<recommended-backup-and-retention-policies>`.
|
|
|
|
For example:
|
|
|
|
.. code-block:: none
|
|
|
|
ssl_ca_certificate_file=<complete path>/<ssl_ca certificates file>
|
|
|
|
E.g.:
|
|
|
|
-e "ssl_ca_certificate_file=/home/sysadmin/new_ca-cert.pem"
|
|
|
|
This parameter depends on ``on_box_data`` value.
|
|
|
|
When ``on_box_data=true`` or not defined, ``ssl_ca_certificate_file``
|
|
will be the location of the ``ssl_ca`` certificate file on the target host.
|
|
This is the default case.
|
|
|
|
When ``on_box_data=false``, ``ssl_ca_certificate_file`` will be the
|
|
location of the ``ssl_ca`` certificate file where the Ansible controller is
|
|
running. This is useful for remote play.
|
|
|
|
.. note::
|
|
|
|
To use this option on local restore mode, you need to download the
|
|
``ssl_ca`` certificate file to the active controller.
|
|
|
|
- The backup contains the bootstrap override values (``localhost.yml``) from
|
|
the time of the backup; for example the registry credentials. There may be
|
|
scenarios where you need to change these values during the restore.
|
|
|
|
You can choose from the two options of overrides below:
|
|
|
|
* ``restore_overrides`` used to override parts of the ``localhost.yml``
|
|
found in backup. By default, entire sections will be modified.
|
|
|
|
For example:
|
|
|
|
To override entire docker registry section:
|
|
|
|
#. Create file ``restore_overrides.yaml``.
|
|
|
|
.. code-block:: none
|
|
|
|
---
|
|
restore_overrides:
|
|
docker_registries:
|
|
defaults:
|
|
type: docker
|
|
username: admin
|
|
password: Hello123!
|
|
docker.elastic.co:
|
|
url: example.com/stx/docker.elastic.co
|
|
docker.io:
|
|
url: example.com/stx/docker.io
|
|
gcr.io:
|
|
url: example.com/stx/gcr.io
|
|
ghcr.io:
|
|
url: example.com/stx/ghcr.io
|
|
icr.io:
|
|
url: example.com/stx/icr.io
|
|
k8s.gcr.io:
|
|
url: example.com/stx/k8s.gcr.io
|
|
quay.io:
|
|
url: example.com/stx/quay.io
|
|
registry.k8s.io:
|
|
url: example.com/stx/registry.k8s.io
|
|
|
|
#. Run restore.
|
|
|
|
.. code-block:: none
|
|
|
|
nsible-playbook restore_platform.yml \
|
|
-e restore_mode=optimized \
|
|
-e "@/path/to/restore_overrides.yaml"
|
|
|
|
|
|
* ``restore_overrides_recursive`` used to override specific fields as
|
|
opposed to entire sections.
|
|
|
|
An example is to override only the registry password without changing
|
|
any of the other values as opposed to the previous example.
|
|
|
|
To override only password:
|
|
|
|
#. Create file ``restore_overrides.yaml``.
|
|
|
|
.. code-block:: none
|
|
|
|
---
|
|
restore_overrides_recursive: true
|
|
restore_overrides:
|
|
docker_registries:
|
|
defaults:
|
|
password: Hello123!
|
|
|
|
|
|
#. Run restore.
|
|
|
|
.. code-block:: none
|
|
|
|
ansible-playbook restore_platform.yml \
|
|
-e restore_mode=optimized \
|
|
-e "@/path/to/restore_overrides.yaml"
|
|
|
|
``-e restore_extra_items``
|
|
Enables the restore playbook to extract additional items from the backup
|
|
during its execution. This is useful when the user has unmanaged files that
|
|
are not included in a normal restore operation.
|
|
|
|
The following is an example of restoring some files that had been manually
|
|
modified on the system pre-backup:
|
|
|
|
.. code-block::
|
|
|
|
ansible-playbook /usr/share/ansible/stx-ansible/playbooks/restore_platform.yml \
|
|
-e "initial_backup_dir=/home/sysadmin" \
|
|
-e "backup_filename=localhost_platform_backup_2024_08_12_22_58_21.tgz"
|
|
-e '{"restore_extra_items": ["etc/pam.d/common-auth", "etc/security/group.conf"]}'
|
|
|
|
.. note::
|
|
|
|
The ``restore_extra_items`` option will restore files only on
|
|
controller-0. The user must restore files on other nodes after they
|
|
are reinstalled, if required.
|
|
|
|
**Legacy**
|
|
|
|
``-e skip_patching=true``
|
|
Patching will not be restored from the backup. With this option, you
|
|
will need to manually restore any patching before running the restore
|
|
playbook.
|
|
|
|
``-e restore_user_images=true``
|
|
Restores the user images created during backup when ``backup_user_images`` was
|
|
true. If the user images are not restored, the images must be pulled from
|
|
upstream or ``registry.central``.
|
|
|
|
**Optimized**
|
|
|
|
``-e restore_registry_filesystem=true``
|
|
Restores the registry images created during backup when
|
|
``backup_registry_filesystem`` was true. If the registry filesystem is not
|
|
restored the images must be pulled from upstream or registry.central.
|
|
|
|
``-e registry_backup_filename=custom_name_registry_filesystem_backup.tgz``
|
|
By default this override is not required. When
|
|
``restore_registry_filesystem`` is true and a custom name was used during
|
|
backup, ``registry_backup_filename`` needs to be set to match. The full
|
|
path will be a combination
|
|
``{initial_backup_dir}/{registry_backup_filename}``
|
|
|
|
.. note::
|
|
|
|
After restore is completed it is not possible to restart (or rerun) the
|
|
restore playbook.
|