doc: document subvolume (group) pins

Fixes: https://tracker.ceph.com/issues/53236
Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>
(cherry picked from commit 6e569bfd1407fb16b66c2b5a758ba6456b9661e2)

diff --git a/doc/cephfs/fs-volumes.rst b/doc/cephfs/fs-volumes.rst
index 203509f83c005325ec360c39e0acf02d757cbb62..6d59ab119b715b0c7d3b34ff8a6a9e3ba826fb0b 100644 (file)
--- a/doc/cephfs/fs-volumes.rst
+++ b/doc/cephfs/fs-volumes.rst
@@ -384,5 +384,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 dcbbfc51e094d1ebb1a20fcc1cbe103fdf5ff55e..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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -136,6 +138,8 @@ directory's export pin. For example:
     # a/b is now pinned to rank 0 and a/ and the rest of its children are still pinned to rank 1
 
 
+.. _cephfs-ephemeral-pinning:
+
 Setting subtree partitioning policies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~