From: Patrick Donnelly <pdonnell@redhat.com>
Date: Thu, 11 Nov 2021 17:30:02 +0000 (-0500)
Subject: doc: document subvolume (group) pins
X-Git-Tag: v17.1.0~454^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=6e569bfd1407fb16b66c2b5a758ba6456b9661e2;p=ceph.git

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 4b42454771c6..aa367b8b29c0 100644
--- 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 5c9df8865e5a..db9b52f3a557 100644
--- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~