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 02564db45a8893e754bce88250667ee135a4d81d..d105c74ad62cbb297b9a7364bd12821f7919c7ff 100644 (file)
--- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~