Merge "Allow overriding overrides in backup during restore"

doc/source/backup/kubernetes/running-restore-playbook-locally-on-the-controller.rst

@@ -18,13 +18,13 @@ following commands to run the Ansible Restore playbook:
 
 .. 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"
+    ~(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>"
+    ~(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:
 
@@ -66,7 +66,7 @@ Below you can find other ``-e`` command line options:
 
        wipe_ceph_osds=true
 
--   To define a convinient place to store the backup files, defined by
+-   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.
@@ -130,6 +130,84 @@ Below you can find other ``-e`` command line options:
         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"
+
 **Legacy**
 
 ``-e skip_patching=true``