From 9e0f39f9d1e3e7a8868a34b7b0f07ee27f623b44 Mon Sep 17 00:00:00 2001 From: Saravanan Manickam Date: Fri, 22 Mar 2024 02:43:13 -0400 Subject: [PATCH] OpenStack Shares Backup management documentation Closes-bug: #2057709 Change-Id: I336a54376e0d55b46cc6f8a8b79e2e5c0c82a04c --- doc/source/admin/index.rst | 1 + .../admin/netapp_cluster_mode_driver.rst | 48 +++ ...d-file-systems-share-backup-management.rst | 322 ++++++++++++++++++ doc/source/user/create-and-manage-shares.rst | 87 +++++ 4 files changed, 458 insertions(+) create mode 100644 doc/source/admin/shared-file-systems-share-backup-management.rst diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 562ed7ffab..f039488ade 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -65,6 +65,7 @@ deployment. capabilities_and_extra_specs group_capabilities_and_extra_specs export_location_metadata + shared-file-systems-share-backup-management.rst Supported share back ends ------------------------- diff --git a/doc/source/admin/netapp_cluster_mode_driver.rst b/doc/source/admin/netapp_cluster_mode_driver.rst index 1d6ade38dc..923e70ac54 100644 --- a/doc/source/admin/netapp_cluster_mode_driver.rst +++ b/doc/source/admin/netapp_cluster_mode_driver.rst @@ -65,6 +65,9 @@ The following operations are supported on Clustered Data ONTAP: - Update a replicated snapshot (DHSS=False) - Migrate share - Migrate share server +- Create share backup +- Restore share backup +- Delete share backup .. note:: @@ -129,6 +132,51 @@ Known restrictions maximum allowed clock skew is 5 minutes. - cDOT supports only flat and VLAN network segmentation types. +How to take backup for NetApp shares +------------------------------------ + +Starting from 2024.1, a concept named ``backup_type`` has been introduced. At +present, it has been implemented for NetApp driver. The ``backup_type`` is a +construct which consists of backup specific configuration parameters such +as ``backup_type_name``, +``netapp_backup_backend_section_name``, ``netapp_backup_vserver``, +``netapp_backup_share``, ``netapp_snapmirror_job_timeout``. + + +.. note:: + The sample config will look like this: + ``eng_data_backup`` is the backup_type here.:: + + [eng_data_backup] + netapp_backup_backend_section_name = ontap2 + netapp_backup_vserver = backup_vserver_name + netapp_backup_volume = backup_volume_name_inside_vserver + netapp_snapmirror_job_timeout = 180 + + [nas_storage] + vendor_name = NetApp + share_driver = manila.share.drivers.netapp.common.NetAppDriver + driver_handles_share_servers = False + netapp_login = admin + .... + .... + enabled_backup_types = eng_data_backup + + + If the option ``netapp_backup_volume`` is not specified, the backup + volume (destination volume) would be created automatically by the driver + inside the vserver. + + The options "netapp_backup_vserver" and "netapp_backup_volume" are optional + and it works as below: + + In case of "driver_handles_share_servers=true", "netapp_backup_vserver" and + "netapp_backup_volume" will be created by driver on "backend" mentioned + under backup type stanza. + In case of "driver_handles_share_servers=false", it will use the existing + vserver of the "backend" mentioned under backup type stanza and will create + the new volume. + The :mod:`manila.share.drivers.netapp.common.py` Module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/admin/shared-file-systems-share-backup-management.rst b/doc/source/admin/shared-file-systems-share-backup-management.rst new file mode 100644 index 0000000000..d087206233 --- /dev/null +++ b/doc/source/admin/shared-file-systems-share-backup-management.rst @@ -0,0 +1,322 @@ +.. _shared-file-systems-share-backup-management: + +======================= +Share backup management +======================= + +Share backup management is the feature that provides the capability to create +a backup for the given share, restore a backup, and delete a backup. It is a +valuable feature for most shared file system users, especially for NAS users. + +Use cases +~~~~~~~~~ + +As an administrator, you may want to backup and restore your share so that +archival can be made simpler and you can bring back the old data +whenever required. It includes: + +* Create a backup +* Delete a backup +* Restore a backup in specified share + + +Backup/Restore workflows +~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting from 2023.2, a generic approach for backing up shares through the +manila data service has been implemented where the backup of the shares can be +stored on a NFS path which are mounted on control nodes. This driver matches +the workflows of cinder NFSBackupDriver and thus it helps users with +less learning time, and provides the basic backup ability. The vendor +that supports NFS, must provide space for NFS to interconnect with NFS backup +drivers. The implementation of NFS backup driver will be generic though. The +backup process for this driver consists of: + +* Make sure share is in available state and not busy. +* Allow read access to share and write access to backup share. +* Mount the share and backend driver's share(i.e. backup share) to the + data service node. +* Copy data from share to backup share. +* Unmount the share and backup share. +* Deny access to share and backup share. + +For the generic NFS backup approach, only one backup backend is allowed for +simplicity, at the moment. By default no backup driver will be enabled. To +enable the backup driver, use the below configurations in manila.conf + +.. code-block:: console + + backup_driver = manila.data.drivers.nfs.NFSBackupDriver + backup_mount_export = :/ + backup_mount_options = '-o vers=',minorversion=1 + +New status for backup and share: + +* backup + + * creating + * available + * deleting + * deleted + * error_deleting + * backup_restoring + * error + +* share + + * backing_creating + * backup_restoring + * backup_restoring_error + +During backup, share will be marked as busy and other operations on share +such as delete, soft_delete, migration, extend, shrink, ummanage, +revert_to_snapshot, crate_snapshot, create_replica etc can not be performed +unless share becomes available. Finally, whether or not the share is +successfully backed up, the state of the share is rolled back to the +available state. In case the backup fails, share task_state will contain the +failure information. Also, failure message will be recorded. + +New clean up actions: +The backup and restore actions could break when service is down, so new +clean up action will be added to reset the status and clean temporary +files (if involved). + +New quotas for backup : + +* ``quota_backups``: indicate the share backups allowed per project. + +* ``quota_backup_gigabytes``: indicate the total amount of storage, in + gigabytes, allowed for backups per project. + +Using the backup APIs (CLI): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The commands to interact with the share backup API are: + +* ``openstack share backup create``: It creates a backup for the share on the + NFS path. The backup becomes creating and it becomes availabe when the backup + is completed. + + .. code-block:: console + + $ openstack share backup create --help # to see the help of all the + available options + + $ openstack share backup create --name manila_backup1 25a6f80e-306e-4bb8-ad27-cf6800955228 + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | availability_zone | manila-zone-0 | + | created_at | 2024-03-21T12:49:35.719214 | + | description | None | + | host | None | + | id | c2022366-0701-44d2-b48b-aa95a666efa5 | + | name | manila_backup1 | + | progress | 0 | + | restore_progress | 0 | + | share_id | 25a6f80e-306e-4bb8-ad27-cf6800955228 | + | size | 1 | + | status | creating | + | topic | None | + | updated_at | None | + +-------------------+--------------------------------------+ + +* ``openstack share backup list``: It prints the current status of the backup. + It is set to ``available`` if all operations succeeded. + + .. code-block:: console + + $ openstack share backup list + +--------------------------------------+----------------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+----------------+--------------------------------------+-----------+ + | c2022366-0701-44d2-b48b-aa95a666efa5 | manila_backup1 | 25a6f80e-306e-4bb8-ad27-cf6800955228 | available | + +--------------------------------------+----------------+--------------------------------------+-----------+ + $ + + +* ``openstack share backup show``: It obtains the latest information of the + backup. + + .. code-block:: console + + $ openstack share backup show c2022366-0701-44d2-b48b-aa95a666efa5 + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | availability_zone | manila-zone-0 | + | created_at | 2024-03-21T12:49:36.000000 | + | description | None | + | host | vm.openstack.opendev.com | + | id | c2022366-0701-44d2-b48b-aa95a666efa5 | + | name | manila_backup1 | + | progress | 100 | + | restore_progress | 0 | + | share_id | 25a6f80e-306e-4bb8-ad27-cf6800955228 | + | size | 1 | + | status | available | + | topic | manila-data | + | updated_at | 2024-03-21T12:50:07.000000 | + +-------------------+--------------------------------------+ + $ + +* ``openstack share backup set``: It sets the name and description for the + backup. + + .. code-block:: console + + $ openstack share backup set c2022366-0701-44d2-b48b-aa95a666efa5 --name "new_name" --description "backup_taken_on_march_21" + + .. note:: + This command has no output. + + .. code-block:: console + + $ openstack share backup show c2022366-0701-44d2-b48b-aa95a666efa5 + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | availability_zone | manila-zone-0 | + | created_at | 2024-03-21T12:49:36.000000 | + | description | backup_taken_on_march_21 | + | host | vm.openstack.opendev.com | + | id | c2022366-0701-44d2-b48b-aa95a666efa5 | + | name | new_name | + | progress | 100 | + | restore_progress | 0 | + | share_id | 25a6f80e-306e-4bb8-ad27-cf6800955228 | + | size | 1 | + | status | available | + | topic | manila-data | + | updated_at | 2024-03-21T12:57:09.000000 | + +-------------------+--------------------------------------+ + + +Using the backup APIs (REST): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +APIs will be experimental, until some cycles of testing, and the eventual +graduation of them. You can refer to this link for more information +`REST API Support `_ + +Backup/Restore via backup types (Vendor specific) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are use cases such that, the individual storage vendors/drivers might +have robust solution in their own storage to backup the data. When such +features are available in the storage, the individual drivers can be enhanced +to build their own backup solutions by extending the existing manila backup +drivers with the use of backup types. Thus shares created in Manila on such +storage, can be easily backed up via vendor specific solutions. + +.. note:: + `backup_type` was added to backup API responses in version 2.85. + +Starting from 2024.1, a concept named ``backup_type`` has been introduced. +This is needed for creating backups with third party drivers, in case an +implementation is available. The ``backup_type`` is a construct which should +have backup specific parameters such as ``backup_type_name`` + + +.. note:: + The sample config will look like this: + ``eng_data_backup`` is the backup_type here.:: + + [eng_data_backup] + backup_type_name=my_backup + + [nas_storage] + enabled_backup_types = eng_data_backup + +Backup/Restore workflows via backup type: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users can create, delete and restore backups on vendor specific storage using +backup_type. + +.. note:: + Before using this feature, you need to check with your storage partner for + the availability of this feature in Manila drivers. + +The workflow of creating, viewing, restoring and deleting backups captured +below for user reference. + + .. code-block:: console + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + +--------------------------------------+-------+--------------------------------------+-----------+ + + $ openstack share backup create --name test5 --backup-options backup_type=eng_data_backup source_share + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | availability_zone | manila-zone-0 | + | backup_type | backup_type1 | + | created_at | 2024-03-11T18:15:32.183982 | + | description | None | + | host | vm.openstack.opendev.com@nas_storage | + | id | 4b468327-d03f-4df7-97ef-c5230b5beafc | + | name | test5 | + | progress | 0 | + | restore_progress | 0 | + | share_id | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | + | size | 1 | + | status | creating | + | topic | None | + | updated_at | None | + +-------------------+--------------------------------------+ + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | creating | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + +--------------------------------------+-------+--------------------------------------+-----------+ + + $ openstack share backup show test5 + +-------------------+------------------------------------------------+ + | Field | Value | + +-------------------+------------------------------------------------+ + | availability_zone | manila-zone-0 | + | backup_type | backup_type1 | + | created_at | 2024-03-11T18:15:32.000000 | + | description | None | + | host | scs000215254-1.nb.openenglab.netapp.com@ontap1 | + | id | 4b468327-d03f-4df7-97ef-c5230b5beafc | + | name | test5 | + | progress | 0 | + | restore_progress | 0 | + | share_id | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | + | size | 1 | + | status | creating | + | topic | manila-share | + | updated_at | 2024-03-11T18:15:32.000000 | + +-------------------+------------------------------------------------+ + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + +--------------------------------------+-------+--------------------------------------+-----------+ + + $ openstack share backup restore test4 + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | restoring | + +--------------------------------------+-------+--------------------------------------+-----------+ + + $ openstack share backup delete test5 + + diff --git a/doc/source/user/create-and-manage-shares.rst b/doc/source/user/create-and-manage-shares.rst index 5d9740c7f3..7c724b691e 100644 --- a/doc/source/user/create-and-manage-shares.rst +++ b/doc/source/user/create-and-manage-shares.rst @@ -1130,3 +1130,90 @@ Resource locks .. code-block:: console $ openstack share lock delete dc7ec691-a505-47d0-b2ec-8eb7fb9270e4 + +Share backups +------------- + +* Create backup + + .. code-block:: console + + $ openstack share backup create --name test5 --backup-options backup_type=eng_data_backup source_share + +-------------------+--------------------------------------+ + | Field | Value | + +-------------------+--------------------------------------+ + | availability_zone | manila-zone-0 | + | backup_type | backup_type1 | + | created_at | 2024-03-11T18:15:32.183982 | + | description | None | + | host | vm.openstack.opendev.com@nas_storage | + | id | 4b468327-d03f-4df7-97ef-c5230b5beafc | + | name | test5 | + | progress | 0 | + | restore_progress | 0 | + | share_id | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | + | size | 1 | + | status | creating | + | topic | None | + | updated_at | None | + +-------------------+--------------------------------------+ + +* List backups + + .. code-block:: console + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | creating | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + +--------------------------------------+-------+--------------------------------------+-----------+ + + $ openstack share backup show test5 + +-------------------+------------------------------------------------+ + | Field | Value | + +-------------------+------------------------------------------------+ + | availability_zone | manila-zone-0 | + | backup_type | backup_type1 | + | created_at | 2024-03-11T18:15:32.000000 | + | description | None | + | host | scs000215254-1.nb.openenglab.netapp.com@ontap1 | + | id | 4b468327-d03f-4df7-97ef-c5230b5beafc | + | name | test5 | + | progress | 0 | + | restore_progress | 0 | + | share_id | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | + | size | 1 | + | status | creating | + | topic | manila-share | + | updated_at | 2024-03-11T18:15:32.000000 | + +-------------------+------------------------------------------------+ + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + +--------------------------------------+-------+--------------------------------------+-----------+ + +* Restore backup + + .. code-block:: console + + $ openstack share backup restore test4 + + $ openstack share backup list + +--------------------------------------+-------+--------------------------------------+-----------+ + | ID | Name | Share ID | Status | + +--------------------------------------+-------+--------------------------------------+-----------+ + | 4b468327-d03f-4df7-97ef-c5230b5beafc | test5 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | available | + | 8a9b3ce0-23bb-4923-b8ce-d0dd1f56b2b8 | test4 | 983c6dd5-ef93-4c73-9359-ef02fe3bbce7 | restoring | + +--------------------------------------+-------+--------------------------------------+-----------+ + +* Delete backup + + .. code-block:: console + + $ openstack share backup delete test5