Export and import Ceph Cinder backup

Created doc "Export and Import Cinder Backups to Ceph Pool" under System Configuration

Added include file downstream

Corrected formatting

Included doc improvements requested by Daniel

Changed format of explaining the commands and removed notes.

Worked on Mary's comments about text formatting.

Signed-off-by: egoncalv <elisamaraaoki.goncalves@windriver.com>
Change-Id: I3e7c74aa6c1c3f76af90cac274badcad040fa42f

doc/source/_includes/export-and-import-cinder-backups-to-ceph-pool.rest

@@ -0,0 +1,2 @@
+.. location-ceph-begin
+.. location-ceph-end

doc/source/system_configuration/openstack/export-and-import-cinder-backups-to-ceph-pool.rst

@@ -0,0 +1,123 @@
+
+.. _export-and-import-cinder-backups-to-ceph-pool:
+
+=============================================
+Export and Import Cinder Backups to Ceph Pool
+=============================================
+
+This document describes how to export and import Cinder backups stored in Ceph
+pool, along with their respective metadata.
+
+.. rubric:: |prereq|
+
+#.  |prefix|-openstack application is applied, up and running.
+
+#.  The user has OpenStack admin credentials.
+
+---------------------------------
+Create and Export a Volume Backup
+---------------------------------
+
+Cinder doesn't guarantee the data consistency during a backup operation, so if
+the volume to be backed up is attached to a running VM and the application in the
+VM is not crash consistent, the recommended approach is to stop the VM for the
+backup procedure. Check the OpenStack documentation
+`Back up and restore volumes and snapshots
+<https://docs.openstack.org/cinder/ussuri/admin/blockstorage-volume-backups.html>`__
+for more details.
+
+.. rubric:: |proc|
+
+#.  Create a volume backup:
+
+    If the volume to be backed up is attached to a running VM, stop the VM first:
+
+    .. code-block:: none
+
+        $ openstack server stop <vm>
+
+    Then, create the backup:
+
+    .. code-block:: none
+
+        $ openstack volume backup create --force [--name <backup_name>] <volume_id>
+
+    where:
+
+    ``--name`` is optional.
+
+    ``--force`` allows you to back up an "in-use" volume.
+
+    .. only:: partner
+
+        .. include:: /_includes/export-and-import-cinder-backups-to-ceph-pool.rest
+            :start-after: location-ceph-begin
+            :end-before: location-ceph-end
+
+#.  Export the backup image from Ceph pool:
+
+    .. code-block:: none
+
+        $ rbd list -p cinder.backups
+        $ rbd export -p cinder.backups <backup_image> <path_to_backup_image_file>
+
+    where ``<backup_image>`` uses the format
+    ``volume-<volume_id>.backup.<backup_id>``.
+
+#.  Export the backup metadata from Cinder database:
+
+    .. code-block:: none
+
+        $ cinder backup-export <backup_id> > <path_to_backup_metadata_file>
+
+----------------------------------
+Import and Restore a Volume Backup
+----------------------------------
+
+.. rubric:: |proc|
+
+#.  Import the backup metadata to Cinder database:
+
+    .. code-block:: none
+
+        $ backup_service=`grep "backup_service" <path_to_backup_metadata_file> | awk '{ print $4 }'`
+        $ backup_url=`grep "backup_url" <path_to_backup_metadata_file> | awk '{ print $4 }'`
+        $ cinder backup-import $backup_service $backup_url
+
+#.  Import the backup image to Ceph pool.
+
+    Check the ID of volume from which the backup was created:
+
+    .. code-block:: none
+
+        $ openstack volume backup show <backup_id>
+
+    Import the backup image to Ceph pool:
+
+    .. code-block:: none
+
+        $ rbd import <path_to_backup_image_file> cinder.backups/volume-<volume_id>.backup.base
+
+#.  Restore the backup to a new volume.
+
+    If the volume in which the backup will be restored is attached to a VM,
+    stop the VM and set the volume status to ``available``:
+
+    .. code-block:: none
+
+        $ openstack server stop <vm>
+        $ openstack volume set --state "available" <new_volume_id>
+
+    Then, restore the backup:
+
+    .. code-block:: none
+
+        $ openstack volume backup restore <backup_id> <new_volume_id>
+
+    If the volume was attached to a VM before the restore operation, set the
+    volume status to ``in-use`` before starting the VM:
+
+    .. code-block:: none
+
+        $ openstack volume set --state "in-use" <new_volume_id>
+        $ openstack server start <vm>

doc/source/system_configuration/openstack/index.rst

@@ -22,4 +22,13 @@ Configure OpenStack Services Using Helm Chart Overrides
    using-helm-overrides-to-enable-internal-dns
    adding-configuration-rpc-response-max-timeout-in-neutron-conf
    assigning-a-dedicated-vlan-id-to-a-target-project-network
-   customize-openstack-horizon-and-login-banner-branding
+   customize-openstack-horizon-and-login-banner-branding
+
+------
+Cinder
+------
+
+.. toctree::
+   :maxdepth: 1
+
+   export-and-import-cinder-backups-to-ceph-pool