docs: balancer: Explain limitations of PG shard count balancing

Signed-off-by: Niklas Hambüchen <mail@nh2.me>

diff --git a/doc/rados/operations/balancer.rst b/doc/rados/operations/balancer.rst
index a797f9be205fbb272e698f2e6db70d2f5c6a38ba..bfd37a10aa494c3fa69b8554b6b7d4df50698c50 100644 (file)
--- 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 <https://github.com/TheJJ/ceph-balancer>`_).
+
 Throttling
 ----------