doc: describe bal_rank_mask configuration

Signed-off-by: Yongseok Oh <yongseok.oh@linecorp.com>

diff --git a/doc/cephfs/multimds.rst b/doc/cephfs/multimds.rst
index db9b52f3a55763634a90bbe841e7b64178014ad0..0193ae748d10d34bf12441ebd040df40e8ca664b 100644 (file)
--- a/doc/cephfs/multimds.rst
+++ b/doc/cephfs/multimds.rst
@@ -225,3 +225,48 @@ 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``.
+
+
+Dynamic subtree partitioning with Balancer on specific ranks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The CephFS file system provides the ``bal_rank_mask`` option to enable the balancer
+to dynamically rebalance subtrees within particular active MDS ranks. This
+allows administrators to employ both the dynamic subtree partitioning and
+static pining schemes in different active MDS ranks so that metadata loads
+are optimized based on user demand. For instance, in realistic cloud
+storage environments, where a lot of subvolumes are allotted to multiple
+computing nodes (e.g., VMs and containers), some subvolumes that require
+high performance are managed by static partitioning, whereas most subvolumes
+that experience a moderate workload are managed by the balancer. As the balancer
+evenly spreads the metadata workload to all active MDS ranks, performance of
+static pinned subvolumes inevitably may be affected or degraded. If this option
+is enabled, subtrees managed by the balancer are not affected by
+static pinned subtrees.
+
+This option can be configured with the ``ceph fs set`` command. For example:
+
+::
+
+    ceph fs set <fs_name> bal_rank_mask <hex> 
+
+Each bitfield of the ``<hex>`` number represents a dedicated rank. If the ``<hex>`` is
+set to ``0x3``, the balancer runs on active ``0`` and ``1`` ranks. For example:
+
+::
+
+    ceph fs set <fs_name> bal_rank_mask 0x3
+
+If the ``bal_rank_mask`` is set to ``-1`` or ``all``, all active ranks are masked
+and utilized by the balancer. As an example:
+
+::
+
+    ceph fs set <fs_name> bal_rank_mask -1
+
+On the other hand, if the balancer needs to be disabled,
+the ``bal_rank_mask`` should be set to ``0x0``. For example:
+
+::
+
+    ceph fs set <fs_name> bal_rank_mask 0x0