doc: document subvolume (group) pins

Fixes: https://tracker.ceph.com/issues/53236
Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>

diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst
index 4b42454771c68d841867df4422fa6aa0a1db577d..aa367b8b29c028eaf51b3f3515b8a95b7cc2c5bb 100644 (file)
--- a/doc/cephfs/fs-volumes.rst
+++ b/doc/cephfs/fs-volumes.rst
@@ -383,5 +383,39 @@ On successful cancelation, the cloned subvolume is moved to `canceled` state::
 
 .. note:: The canceled cloned can be deleted by using --force option in `fs subvolume rm` command.
 
+
+.. _subvol-pinning:
+
+Pinning Subvolumes and Subvolume Groups
+---------------------------------------
+
+
+Subvolumes and subvolume groups can be automatically pinned to ranks according
+to policies. This can help distribute load across MDS ranks in predictable and
+stable ways.  Review :ref:`cephfs-pinning` and :ref:`cephfs-ephemeral-pinning`
+for details on how pinning works.
+
+Pinning is configured by::
+
+  $ ceph fs subvolumegroup pin <vol_name> <group_name> <pin_type> <pin_setting>
+
+or for subvolumes::
+
+  $ ceph fs subvolume pin <vol_name> <group_name> <pin_type> <pin_setting>
+
+Typically you will want to set subvolume group pins. The ``pin_type`` may be
+one of ``export``, ``distributed``, or ``random``. The ``pin_setting``
+corresponds to the extended attributed "value" as in the pinning documentation
+referenced above.
+
+So, for example, setting a distributed pinning strategy on a subvolume group::
+
+  $ ceph fs subvolumegroup pin cephfilesystem-a csi distributed 1
+
+Will enable distributed subtree partitioning policy for the "csi" subvolume
+group.  This will cause every subvolume within the group to be automatically
+pinned to one of the available ranks on the file system.
+
+
 .. _manila: https://github.com/openstack/manila
 .. _CSI: https://github.com/ceph/ceph-csi

diff --git a/doc/cephfs/multimds.rst b/doc/cephfs/multimds.rst
index 5c9df8865e5ac26cd38a884ef38f089400ca051c..db9b52f3a55763634a90bbe841e7b64178014ad0 100644 (file)
--- a/doc/cephfs/multimds.rst
+++ b/doc/cephfs/multimds.rst
@@ -100,6 +100,8 @@ When a daemon finishes stopping, it will respawn itself and go back to being a
 standby.
 
 
+.. _cephfs-pinning:
+
 Manually pinning directory trees to a particular rank
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~