From 8f83ec546aa16c3e06f1a2b1cbf4c8f657771f55 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Niklas=20Hamb=C3=BCchen?= Date: Sun, 10 May 2026 03:35:52 +0000 Subject: [PATCH] docs: balancer: Explain limitations of PG shard count balancing MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Niklas Hambüchen --- doc/rados/operations/balancer.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/rados/operations/balancer.rst b/doc/rados/operations/balancer.rst index a797f9be205..bfd37a10aa4 100644 --- a/doc/rados/operations/balancer.rst +++ b/doc/rados/operations/balancer.rst @@ -39,6 +39,22 @@ combines the upmap balancer with the read balancer so that both writes and reads are optimized. ``read`` mode can be used when only read optimization is desired. For more details, see :ref:`read_balancer`. +Limitation: count-based balancing vs. size-based balancing +---------------------------------------------------------- + +Ceph's built-in balancer optimizes only by **PG shard count**, not by the +actual size of the data stored in each PG. + +This can result in clusters whose OSDs are balanced by PG shard count, +but very imbalanced by stored Bytes. +At the pool level, this can cause a pool's ``%USED`` (from ``ceph df``) +to be much higher than the cluster's ``%RAW USED``, because the +pool's fullest OSD (which determines the pool's available space) may be +disproportionately loaded with large PGs. + +Size-aware community balancers exist (for example, +`jj-balancer `_). + Throttling ---------- -- 2.47.3