doc: Document erasure-coded pool direct reads for balance flag

Signed-off-by: Jon Bailey <jonathan.bailey1@ibm.com>

diff --git a/doc/man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst
index ba4d0bb918c3fc658bbcb2c6368b9c145483782a..2107f5a98b11b41e6a23a0731266affad4e3896c 100644 (file)
--- 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 348d8d79716aefd0cbd6431bb93ae38ab9d5c24c..880d65eac001b998549a89cb0931991e4551abb4 100644 (file)
--- 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 b12e2edc44e96c709fdf8b97198e0d459500f66e..456bb1b801c1548081f6569459d2af9ff3445fa3 100644 (file)
--- 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