From: Jon Bailey Date: Wed, 3 Jun 2026 10:42:29 +0000 (+0100) Subject: doc: Document erasure-coded pool direct reads for balance flag X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=9b8e6f91029923fae5a29d7d52a2624edf902fe3;p=ceph.git doc: Document erasure-coded pool direct reads for balance flag Signed-off-by: Jon Bailey --- diff --git a/doc/man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst index ba4d0bb918c..2107f5a98b1 100644 --- a/doc/man/8/mount.ceph.rst +++ b/doc/man/8/mount.ceph.rst @@ -229,6 +229,11 @@ Advanced - ``balance``: When a replicated pool receives a read request, pick a random OSD from the PG's acting set to serve it (since 5.8). + When an erasure-coded pool receives a read request, pick the shard that + stores the data, giving a performance uplift over routing the request via + the primary (requires Umbrella server and client; kernel client support is + planned for a future release). + This mode is safe for general use only since Octopus (i.e. after `ceph osd require-osd-release octopus`). Otherwise it should be limited to read-only workloads such as snapshots. diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst index 348d8d79716..880d65eac00 100644 --- a/doc/man/8/rbd.rst +++ b/doc/man/8/rbd.rst @@ -870,6 +870,11 @@ Per mapping (block device) `rbd device map` options: * read_from_replica=balance - When issued a read on a replicated pool, pick a random OSD for serving it (since 5.8). + When issued a read on an erasure-coded pool, pick the shard that stores the + data, giving a performance uplift over routing the request via the primary + (requires Umbrella server and client; kernel client support is planned for a + future release). + This mode is safe for general use only since Octopus (i.e. after "ceph osd require-osd-release octopus"). Otherwise it should be limited to read-only workloads such as images mapped read-only everywhere or snapshots. diff --git a/src/common/options/rbd.yaml.in b/src/common/options/rbd.yaml.in index b12e2edc44e..456bb1b801c 100644 --- a/src/common/options/rbd.yaml.in +++ b/src/common/options/rbd.yaml.in @@ -364,8 +364,9 @@ options: Policy for determining which OSD will receive read operations. If set to ``default``, each PG's primary OSD will always be used for read operations. If set to ``balance``, read operations will - be sent to a randomly selected OSD within the replica set. If set - to ``localize``, read operations will be sent to the closest OSD + be sent to a randomly selected OSD within the replica set for replica + pools or directly to the shard storing the data for erasure-coded pools. + If set to ``localize``, read operations will be sent to the closest OSD as determined by the CRUSH map. Unlike ``rbd_balance_snap_reads`` and ``rbd_localize_snap_reads`` or ``rbd_balance_parent_reads`` and ``rbd_localize_parent_reads``, it affects all read operations, not