From: Shyamsundar Ranganathan <srangana@redhat.com>
Date: Tue, 21 Jul 2020 13:43:18 +0000 (-0400)
Subject: mgr/volumes: Add documentation regarding --retain-snapshots option
X-Git-Tag: wip-pdonnell-testing-20200918.022351~489^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=61e118ff6db4840c2d27bacc1bb718cec9d6b3c6;p=ceph-ci.git

mgr/volumes: Add documentation regarding --retain-snapshots option

Signed-off-by: Shyamsundar Ranganathan <srangana@redhat.com>
---

diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst
index f9994ce6edf..e5811041ae7 100644
--- a/doc/cephfs/fs-volumes.rst
+++ b/doc/cephfs/fs-volumes.rst
@@ -65,7 +65,7 @@ FS Subvolume groups
 
 Create a subvolume group using::
 
-    $ ceph fs subvolumegroup create <vol_name> <group_name> [--pool_layout <data_pool_name> --uid <uid> --gid <gid> --mode <octal_mode>]
+    $ ceph fs subvolumegroup create <vol_name> <group_name> [--pool_layout <data_pool_name>] [--uid <uid>] [--gid <gid>] [--mode <octal_mode>]
 
 The command succeeds even if the subvolume group already exists.
 
@@ -115,7 +115,7 @@ FS Subvolumes
 
 Create a subvolume using::
 
-    $ ceph fs subvolume create <vol_name> <subvol_name> [--size <size_in_bytes> --group_name <subvol_group_name> --pool_layout <data_pool_name> --uid <uid> --gid <gid> --mode <octal_mode> --namespace-isolated]
+    $ ceph fs subvolume create <vol_name> <subvol_name> [--size <size_in_bytes>] [--group_name <subvol_group_name>] [--pool_layout <data_pool_name>] [--uid <uid>] [--gid <gid>] [--mode <octal_mode>] [--namespace-isolated]
 
 
 The command succeeds even if the subvolume already exists.
@@ -130,16 +130,24 @@ its parent directory and no size limit.
 
 Remove a subvolume using::
 
-    $ ceph fs subvolume rm <vol_name> <subvol_name> [--group_name <subvol_group_name> --force]
+    $ ceph fs subvolume rm <vol_name> <subvol_name> [--group_name <subvol_group_name>] [--force] [--retain-snapshots]
 
 
 The command removes the subvolume and its contents. It does this in two steps.
-First, it move the subvolume to a trash folder, and then asynchronously purges
+First, it moves the subvolume to a trash folder, and then asynchronously purges
 its contents.
 
 The removal of a subvolume fails if it has snapshots, or is non-existent.
 '--force' flag allows the non-existent subvolume remove command to succeed.
 
+A subvolume can be removed retaining existing snapshots of the subvolume using the
+'--retain-snapshots' option. If snapshots are retained, the subvolume is considered
+empty for all operations not involving the retained snapshots.
+
+.. note:: Snapshot retained subvolumes can be recreated using 'ceph fs subvolume create'
+
+.. note:: Retained snapshots can be used as a clone source to recreate the subvolume, or clone to a newer subvolume.
+
 Resize a subvolume using::
 
     $ ceph fs subvolume resize <vol_name> <subvol_name> <new_size> [--group_name <subvol_group_name>] [--no_shrink]
@@ -175,17 +183,32 @@ The output format is json and contains fields as follows.
 * type: subvolume type indicating whether it's clone or subvolume
 * pool_namespace: RADOS namespace of the subvolume
 * features: features supported by the subvolume
+* state: current state of the subvolume
+
+If a subvolume has been removed retaining its snapshots, the output only contains fields as follows.
+
+* type: subvolume type indicating whether it's clone or subvolume
+* features: features supported by the subvolume
+* state: current state of the subvolume
 
 The subvolume "features" are based on the internal version of the subvolume and is a list containing
 a subset of the following features,
 
 * "snapshot-clone": supports cloning using a subvolumes snapshot as the source
 * "snapshot-autoprotect": supports automatically protecting snapshots, that are active clone sources, from deletion
+* "snapshot-retention": supports removing subvolume contents, retaining any existing snapshots
+
+The subvolume "state" is based on the current state of the subvolume and contains one of the following values.
+
+* "complete": subvolume is ready for all operations
+* "snapshot-retained": subvolume is removed but its snapshots are retained
 
 List subvolumes using::
 
     $ ceph fs subvolume ls <vol_name> [--group_name <subvol_group_name>]
 
+.. note:: subvolumes that are removed but have snapshots retained, are also listed.
+
 Create a snapshot of a subvolume using::
 
     $ ceph fs subvolume snapshot create <vol_name> <subvol_name> <snap_name> [--group_name <subvol_group_name>]
@@ -193,11 +216,13 @@ Create a snapshot of a subvolume using::
 
 Remove a snapshot of a subvolume using::
 
-    $ ceph fs subvolume snapshot rm <vol_name> <subvol_name> <snap_name> [--group_name <subvol_group_name> --force]
+    $ ceph fs subvolume snapshot rm <vol_name> <subvol_name> <snap_name> [--group_name <subvol_group_name>] [--force]
 
 Using the '--force' flag allows the command to succeed that would otherwise
 fail if the snapshot did not exist.
 
+.. note:: if the last snapshot within a snapshot retained subvolume is removed, the subvolume is also removed
+
 List snapshots of a subvolume using::
 
     $ ceph fs subvolume snapshot ls <vol_name> <subvol_name> [--group_name <subvol_group_name>]