doc: clarify distributed ephemeral pins new mechanism

This documentation was for the old code, the new code (by Zheng)
fragments the directory and distributes those fragments.

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

diff --git a/doc/cephfs/multimds.rst b/doc/cephfs/multimds.rst
index e22a84fac813727547828ac7ffc49d82f3113d8c..dcbbfc51e094d1ebb1a20fcc1cbe103fdf5ff55e 100644 (file)
--- a/doc/cephfs/multimds.rst
+++ b/doc/cephfs/multimds.rst
@@ -162,10 +162,12 @@ your metadata throughput with no other administrative intervention.
 
 Presently, there are two types of ephemeral pinning:
 
-**Distributed Ephemeral Pins**: This policy indicates that **all** of a
-directory's immediate children should be ephemerally pinned. The canonical
-example would be the ``/home`` directory: we want every user's home directory
-to be spread across the entire MDS cluster. This can be set via:
+**Distributed Ephemeral Pins**: This policy causes a directory to fragment
+(even well below the normal fragmentation thresholds) and distribute its
+fragments as ephemerally pinned subtrees. This has the effect of distributing
+immediate children across a range of MDS ranks.  The canonical example use-case
+would be the ``/home`` directory: we want every user's home directory to be
+spread across the entire MDS cluster. This can be set via:
 
 ::
 
@@ -219,18 +221,3 @@ For the reverse situation:
 
 The ``home/patrick`` directory and its children will be pinned to rank 2
 because its export pin overrides the policy on ``home``.
-
-If a directory has an export pin and an ephemeral pin policy, the export pin
-applies to the directory itself and the policy to its children. So:
-
-::
-
-    mkdir -p home/{patrick,john}
-    setfattr -n ceph.dir.pin -v 0 home
-    setfattr -n ceph.dir.pin.distributed -v 1 home
-
-The home directory inode (and all of its directory fragments) will always be
-located on rank 0. All children including ``home/patrick`` and ``home/john``
-will be ephemerally pinned according to the distributed policy. This may only
-matter for some obscure performance advantages. All the same, it's mentioned
-here so the override policy is clear.