From 80de0a3c92d54d644a0ea3d8120f1f8f445ea2e0 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Mon, 23 Jun 2025 22:50:03 +1000 Subject: [PATCH] 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 --- doc/rados/operations/balancer.rst | 14 ++++++++------ src/common/options/global.yaml.in | 5 +++++ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/doc/rados/operations/balancer.rst b/doc/rados/operations/balancer.rst index 8789df70cf552..f30f19a30f8ab 100644 --- 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 0999c791ba67f..6122ac275771f 100644 --- 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 -- 2.39.5