doc/rados: clarify "upmap_max_deviation"

Clarify the threshold set by "upmap_max_deviation" and add the
information about this configurable that is currently in
src/pybind/mgr/balancer/module.py to src/common/options/global.yaml.in,
so that it will be accessible by means of ".. confval::" declarations.

Fixes: https://tracker.ceph.com/issues/71796
Signed-off-by: Zac Dover <zac.dover@proton.me>

diff --git a/doc/rados/operations/balancer.rst b/doc/rados/operations/balancer.rst
index 8789df70cf5521b00d611f2e216305aa96da9a86..f30f19a30f8abdb656d5326d8145da77bab6611e 100644 (file)
--- a/doc/rados/operations/balancer.rst
+++ b/doc/rados/operations/balancer.rst
@@ -60,12 +60,14 @@ of the following form:
 A larger value may increase the speed of cluster balancing / convergence
 at the potential cost of greater impact on client operations.
 
-There is a separate setting ``upmap_max_deviation`` for how uniform the
-distribution of PGs must be for the module to consider the cluster adequately
-balanced.  At the time of writing (June 2025), this value defaults to ``5``,
-which means that if a given OSD's PG replicas vary by five or fewer above or
-below the cluster's average, it will be considered sufficiently balanced.
-
+The setting ``upmax_max_deviation`` sets the threshold at which the balancer
+module considers the cluster's distribution of PGs adequately balanced. At the
+time of writing (June 2025), this value defaults to ``5``, which means that a
+given OSD's PG replicas are considered adequately balanced when they vary by
+five or fewer above or below the cluster's average. Here are the details of
+this configurable:
+
+.. confval:: upmap_max_deviation
 
 This value of PG replicas / shards (as distinct from logical PGs) is reported
 by the ``ceph osd df`` command under the ``PGS`` column and the variance

diff --git a/src/common/options/global.yaml.in b/src/common/options/global.yaml.in
index 0999c791ba67f1f97421e997a3fb7dc111d96a15..6122ac275771f0787c58ec372340c4c8847ee1ab 100644 (file)
--- a/src/common/options/global.yaml.in
+++ b/src/common/options/global.yaml.in
@@ -6834,3 +6834,8 @@ options:
   level: dev
   default: 0
   desc: When EC writes should generate PDWs (development only) 0=optimal 1=never 2=when possible
+- name: upmap_max_deviation 
+  type: int
+  level: unknown (fixme)
+  default: 5
+  desc: If the number of PGs is within this count then no optimization is attempted