doc/rados/operations/pools.rst: Added docs for stretch pool set|unset|show

Fixes: https://tracker.ceph.com/issues/64802
Signed-off-by: Kamoltat <ksirivad@redhat.com>
(cherry picked from commit fb0011a692c656db0c64bbeb7d47d79cc62b16c9)

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index c3fe3b7d82ee6330fdcfe78d6638d368422887ef..9da4825099bde637da5aeafadd49449bc98993dd 100644 (file)
--- a/doc/rados/operations/pools.rst
+++ b/doc/rados/operations/pools.rst
@@ -737,6 +737,117 @@ Managing pools that are flagged with ``--bulk``
 ===============================================
 See :ref:`managing_bulk_flagged_pools`.
 
+Setting values for a stretch pool
+=================================
+To set values for a stretch pool, run a command of the following form:
+
+.. prompt:: bash $
+
+   ceph osd pool stretch set {pool-name} {peering_crush_bucket_count} {peering_crush_bucket_target} {peering_crush_bucket_barrier} {crush_rule} {size} {min_size} [--yes-i-really-mean-it]
+
+Here are the break downs of the arguments:
+
+.. describe:: {pool-name}
+
+   The name of the pool. It must be an existing pool, this command doesn't create a new pool.
+
+   :Type: String
+   :Required: Yes.
+
+.. describe:: {peering_crush_bucket_count}
+
+   The value is used along with peering_crush_bucket_barrier to determined whether the set of
+   OSDs in the chosen acting set can peer with each other, based on the number of distinct
+   buckets there are in the acting set.
+
+   :Type: Integer
+   :Required: Yes.
+
+.. describe:: {peering_crush_bucket_target}
+   
+   This value is used along with peering_crush_bucket_barrier and size to calculate
+   the value bucket_max which limits the number of OSDs in the same bucket from getting chose to be in the acting set of a PG.
+   
+   :Type: Integer
+   :Required: Yes.
+
+.. describe:: {peering_crush_bucket_barrier}
+      
+   The type of bucket a pool is stretched across, e.g., rack, row, or datacenter.
+
+   :Type: String
+   :Required: Yes.
+
+.. describe:: {crush_rule}
+      
+   The crush rule to use for the stretch pool. The type of pool must match the type of crush_rule
+   (replicated or erasure).
+
+   :Type: String
+   :Required: Yes.
+
+.. describe:: {size}
+         
+   The number of replicas for objects in the stretch pool.
+   
+   :Type: Integer
+   :Required: Yes.
+
+.. describe:: {min_size}
+            
+   The minimum number of replicas required for I/O in the stretch pool.
+
+   :Type: Integer
+   :Required: Yes.
+
+.. describe:: {--yes-i-really-mean-it}
+   
+      This flag is required to confirm that you really want to by-pass
+      the safety checks and set the values for a stretch pool, e.g,
+      when you are trying to set ``peering_crush_bucket_count`` or 
+      ``peering_crush_bucket_target`` to be more than the number of buckets in the crush map.
+   
+      :Type: Flag
+      :Required: No.
+
+.. _setting_values_for_a_stretch_pool:
+
+Unsetting values for a stretch pool
+===================================
+To move the pool back to non-stretch, run a command of the following form:
+
+.. prompt:: bash $
+
+   ceph osd pool stretch unset {pool-name}
+
+Here are the break downs of the argument:
+
+.. describe:: {pool-name}
+
+   The name of the pool. It must be an existing pool that is stretched,
+   i.e., it has already been set with the command `ceph osd pool stretch set`.
+
+   :Type: String
+   :Required: Yes.
+
+Showing values of a stretch pool
+================================
+To show values for a stretch pool, run a command of the following form:
+
+.. prompt:: bash $
+
+   ceph osd pool stretch show {pool-name}
+
+Here are the break downs of the argument:
+
+.. describe:: {pool-name}
+
+   The name of the pool. It must be an existing pool that is stretched,
+   i.e., it has already been set with the command `ceph osd pool stretch set`.
+
+   :Type: String
+   :Required: Yes.
+
 .. _Pool, PG and CRUSH Config Reference: ../../configuration/pool-pg-config-ref
 .. _Bloom Filter: https://en.wikipedia.org/wiki/Bloom_filter
 .. _setting the number of placement groups: ../placement-groups#set-the-number-of-placement-groups

diff --git a/doc/rados/operations/stretch-mode.rst b/doc/rados/operations/stretch-mode.rst
index 37c1de14b838c442305299aa6309a5430e3c2a10..a5694718a5847cdba74ef092f2b97cafd6ca44ae 100644 (file)
--- a/doc/rados/operations/stretch-mode.rst
+++ b/doc/rados/operations/stretch-mode.rst
@@ -81,6 +81,18 @@ Data Center B. In a situation of this kind, the loss of Data Center A means
 that the data is lost and Ceph will not be able to operate on it. This
 situation is surprisingly difficult to avoid using only standard CRUSH rules.
 
+Individual Stretch Pools
+========================
+Setting individual ``stretch pool`` is an option that allows for the configuration
+of specific pools to be distributed across ``two or more data centers``.
+This is achieved by executing the ``ceph osd pool stretch set`` command on each desired pool,
+as opposed to applying a cluster-wide configuration ``with stretch mode``.
+See :ref:`setting_values_for_a_stretch_pool`
+
+Use ``stretch mode`` when you have exactly ``two data centers`` and require a uniform
+configuration across the entire cluster. Conversely, opt for a ``stretch pool``
+when you need a particular pool to be replicated across ``more than two data centers``,
+providing a more granular level of control and a larger cluster size.
 
 Stretch Mode
 ============