From: Patrick Donnelly <pdonnell@redhat.com>
Date: Tue, 12 Dec 2023 16:45:05 +0000 (-0500)
Subject: doc/cephfs: add docs for balance_automate
X-Git-Tag: testing/wip-batrick-testing-20240411.154038~781^2~4
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=08a342485c9ffc957e959ad3f5d4abc3b092bfb0;p=ceph-ci.git

doc/cephfs: add docs for balance_automate

Signed-off-by: Patrick Donnelly <pdonnell@redhat.com>
---

diff --git a/doc/cephfs/multimds.rst b/doc/cephfs/multimds.rst
index 02564db45a8..d105c74ad62 100644
--- a/doc/cephfs/multimds.rst
+++ b/doc/cephfs/multimds.rst
@@ -243,6 +243,31 @@ value to `-1`.
    $ setfattr -n ceph.dir.pin -v -1 home
 
 
+Dynamic Subtree Partitioning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CephFS has long had a dynamic metadata blanacer (sometimes called the "default
+balancer") which can split or merge subtrees while placing them on "colder" MDS
+ranks. Moving the metadata around can improve overall file system throughput
+and cache size.
+
+However, the balancer has suffered from problem with efficiency and performance
+so it is by default turned off. This is to avoid an administrator "turning on
+multimds" by increasing the ``max_mds`` setting and then finding the balancer
+has made a mess of the cluster performance (reverting is straightforward but
+can take time).
+
+The setting to turn on the balancer is:
+
+.. prompt:: bash #
+
+   ceph fs set <fs_name> balance_automate true
+
+Turning on the balancer should only be done with appropriate configuration,
+such as with the ``bal_rank_mask`` setting (described below). Careful
+monitoring of the file system performance and MDS is advised.
+
+
 Dynamic subtree partitioning with Balancer on specific ranks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~