import 15.2.9

[ceph.git] / ceph / doc / cephfs / fs-volumes.rst

diff --git a/ceph/doc/cephfs/fs-volumes.rst b/ceph/doc/cephfs/fs-volumes.rst
index 8073403349692ebd4a56b3a44f5dd268704dffac..dd38e38e419bb7e6e8818314b352976f70f7e881 100644 (file)
--- a/ceph/doc/cephfs/fs-volumes.rst
+++ b/ceph/doc/cephfs/fs-volumes.rst
@@ -85,7 +85,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.
 
@@ -111,12 +111,8 @@ List subvolume groups using::
 
     $ ceph fs subvolumegroup ls <vol_name>
 
-Create a snapshot (see :doc:`/cephfs/experimental-features`) of a
-subvolume group using::
-
-    $ ceph fs subvolumegroup snapshot create <vol_name> <group_name> <snap_name>
-
-This implicitly snapshots all the subvolumes under the subvolume group.
+.. note:: Subvolume group snapshot feature is no longer supported in mainline CephFS (existing group
+          snapshots can still be listed and deleted)
 
 Remove a snapshot of a subvolume group using::
 
@@ -135,7 +131,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.
@@ -150,16 +146,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]
@@ -195,17 +199,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>]
@@ -213,11 +232,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>]