doc/rbd/rbd-config-ref: use confval directive to define options

less repeating this way.

also fix a typo of "rbd_qos_writ_bps_limit", it should be
"rbd_qos_write_bps_limit".

Signed-off-by: Kefu Chai <kchai@redhat.com>

diff --git a/doc/rbd/rbd-config-ref.rst b/doc/rbd/rbd-config-ref.rst
index 777894cd6c3992d1c295b7959b33869594253b22..2e391a217ca71d3d5949e9a2c1cb1ba098f11ff9 100644 (file)
--- a/doc/rbd/rbd-config-ref.rst
+++ b/doc/rbd/rbd-config-ref.rst
@@ -7,33 +7,8 @@ See `Block Device`_ for additional details.
 Generic IO Settings
 ===================
 
-``rbd_compression_hint``
-
-:Description: Hint to send to the OSDs on write operations. If set to 
-              ``compressible`` and the OSD ``bluestore_compression_mode``
-              setting is ``passive``, the OSD will attempt to compress data
-              If set to ``incompressible`` and the OSD compression setting
-              is ``aggressive``, the OSD will not attempt to compress data.
-:Type: Enum
-:Required: No
-:Default: ``none``
-:Values: ``none``, ``compressible``, ``incompressible``
-
-
-``rbd_read_from_replica_policy``
-
-:Description: 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
-              as determined by the CRUSH map. Note: this feature requires the
-              cluster to be configured with a minimum compatible OSD release of
-              Octopus.
-:Type: Enum
-:Required: No
-:Default: ``default``
-:Values: ``default``, ``balance``, ``localize``
+.. confval:: rbd_compression_hint
+.. confval:: rbd_read_from_replica_policy
 
 Cache Settings
 =======================
@@ -82,72 +57,13 @@ Option settings for RBD should be set in the ``[client]``
 section of your configuration file or the central config store. These settings
 include:
 
-``rbd_cache``
-
-:Description: Enable caching for RADOS Block Device (RBD).
-:Type: Boolean
-:Required: No
-:Default: ``true``
-
-
-``rbd_cache_policy``
-
-:Description: Select the caching policy for librbd.
-:Type: Enum
-:Required: No
-:Default: ``writearound``
-:Values: ``writearound``, ``writeback``, ``writethrough``
-
-
-``rbd_cache_writethrough_until_flush``
-
-:Description: Start out in ``writethrough`` mode, and switch to ``writeback``
-              after the first flush request is received. Enabling is a
-              conservative but safe strategy in case VMs running on RBD volumes
-              are too old to send flushes, like the ``virtio`` driver in Linux
-              kernels older than 2.6.32.
-:Type: Boolean
-:Required: No
-:Default: ``true``
-
-
-``rbd_cache_size``
-
-:Description: The per-volume RBD client cache size in bytes.
-:Type: 64-bit Integer
-:Required: No
-:Default: ``32 MiB``
-:Policies: write-back and write-through
-
-
-``rbd_cache_max_dirty``
-
-:Description: The ``dirty`` limit in bytes at which the cache triggers write-back.  If ``0``, uses write-through caching.
-:Type: 64-bit Integer
-:Required: No
-:Constraint: Must be less than ``rbd_cache_size``.
-:Default: ``24 MiB``
-:Policies: write-around and write-back
-
-
-``rbd_cache_target_dirty``
-
-:Description: The ``dirty target`` before the cache begins writing data to the data storage. Does not block writes to the cache.
-:Type: 64-bit Integer
-:Required: No
-:Constraint: Must be less than ``rbd_cache_max_dirty``.
-:Default: ``16 MiB``
-:Policies: write-back
-
-
-``rbd_cache_max_dirty_age``
-
-:Description: The number of seconds dirty data is in the cache before writeback starts. 
-:Type: Float
-:Required: No
-:Default: ``1.0``
-:Policies: write-back
-
+.. confval:: rbd_cache
+.. confval:: rbd_cache_policy
+.. confval:: rbd_cache_writethrough_until_flush
+.. confval:: rbd_cache_size
+.. confval:: rbd_cache_max_dirty
+.. confval:: rbd_cache_target_dirty
+.. confval:: rbd_cache_max_dirty_age
 
 .. _Block Device: ../../rbd
 
@@ -161,32 +77,9 @@ but boot loaders may not issue efficient reads. Read-ahead is automatically
 disabled if caching is disabled or if the policy is write-around.
 
 
-``rbd_readahead_trigger_requests``
-
-:Description: Number of sequential read requests necessary to trigger read-ahead.
-:Type: Integer
-:Required: No
-:Default: ``10``
-
-
-``rbd_readahead_max_bytes``
-
-:Description: Maximum size of a read-ahead request.  If zero, read-ahead is disabled.
-:Type: 64-bit Integer
-:Required: No
-:Default: ``512 KiB``
-
-
-``rbd_readahead_disable_after_bytes``
-
-:Description: After this many bytes have been read from an RBD image, read-ahead
-              is disabled for that image until it is closed.  This allows the
-              guest OS to take over read-ahead once it is booted.  If zero,
-              read-ahead stays enabled.
-:Type: 64-bit Integer
-:Required: No
-:Default: ``50 MiB``
-
+.. confval:: rbd_readahead_trigger_requests
+.. confval:: rbd_readahead_max_bytes
+.. confval:: rbd_readahead_disable_after_bytes
 
 Image Features
 ==============
@@ -324,153 +217,22 @@ QOS Settings
 librbd supports limiting per-image IO, controlled by the following
 settings.
 
-``rbd_qos_iops_limit``
-
-:Description: The desired limit of IO operations per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_bps_limit``
-
-:Description: The desired limit of IO bytes per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_read_iops_limit``
-
-:Description: The desired limit of read operations per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_write_iops_limit``
-
-:Description: The desired limit of write operations per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_read_bps_limit``
-
-:Description: The desired limit of read bytes per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_writ_bps_limit``
-
-:Description: The desired limit of write bytes per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_iops_burst``
-
-:Description: The desired burst limit of IO operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_bps_burst``
-
-:Description: The desired burst limit of IO bytes.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_read_iops_burst``
-
-:Description: The desired burst limit of read operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_write_iops_burst``
-
-:Description: The desired burst limit of write operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_read_bps_burst``
-
-:Description: The desired burst limit of read bytes per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_write_bps_burst``
-
-:Description: The desired burst limit of write bytes per second.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``0``
-
-
-``rbd_qos_iops_burst_seconds``
-
-:Description: The desired burst duration in seconds of IO operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_bps_burst_seconds``
-
-:Description: The desired burst duration in seconds.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_read_iops_burst_seconds``
-
-:Description: The desired burst duration in seconds of read operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_write_iops_burst_seconds``
-
-:Description: The desired burst duration in seconds of write operations.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_read_bps_burst_seconds``
-
-:Description: The desired burst duration in seconds of read bytes.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_write_bps_burst_seconds``
-
-:Description: The desired burst duration in seconds of write bytes.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``1``
-
-
-``rbd_qos_schedule_tick_min``
-
-:Description: The minimum schedule tick (in milliseconds) for QoS.
-:Type: Unsigned Integer
-:Required: No
-:Default: ``50``
+.. confval:: rbd_qos_iops_limit
+.. confval:: rbd_qos_bps_limit
+.. confval:: rbd_qos_read_iops_limit
+.. confval:: rbd_qos_write_iops_limit
+.. confval:: rbd_qos_read_bps_limit
+.. confval:: rbd_qos_write_bps_limit
+.. confval:: rbd_qos_iops_burst
+.. confval:: rbd_qos_bps_burst
+.. confval:: rbd_qos_read_iops_burst
+.. confval:: rbd_qos_write_iops_burst
+.. confval:: rbd_qos_read_bps_burst
+.. confval:: rbd_qos_write_bps_burst
+.. confval:: rbd_qos_iops_burst_seconds
+.. confval:: rbd_qos_bps_burst_seconds
+.. confval:: rbd_qos_read_iops_burst_seconds
+.. confval:: rbd_qos_write_iops_burst_seconds
+.. confval:: rbd_qos_read_bps_burst_seconds
+.. confval:: rbd_qos_write_bps_burst_seconds
+.. confval:: rbd_qos_schedule_tick_min

diff --git a/src/common/options/rbd.yaml.in b/src/common/options/rbd.yaml.in
index 871f508d824a4f0fcf0ca96b34c588fa587001b9..e99cab3d2cf274d4d1f52ca15106ec2132bfeeb2 100644 (file)
--- a/src/common/options/rbd.yaml.in
+++ b/src/common/options/rbd.yaml.in
@@ -100,6 +100,7 @@ options:
   type: bool
   level: advanced
   desc: whether to enable caching (writeback unless rbd_cache_max_dirty is 0)
+  fmt_desc: Enable caching for RADOS Block Device (RBD).
   default: true
   services:
   - rbd
@@ -107,6 +108,7 @@ options:
   type: str
   level: advanced
   desc: cache policy for handling writes.
+  fmt_desc: Select the caching policy for librbd.
   default: writearound
   services:
   - rbd
@@ -119,6 +121,11 @@ options:
   level: advanced
   desc: whether to make writeback caching writethrough until flush is called, to be
     sure the user of librbd will send flushes so that writeback is safe
+  fmt_desc: Start out in ``writethrough`` mode, and switch to ``writeback``
+    after the first flush request is received. Enabling is a
+    conservative but safe strategy in case VMs running on RBD volumes
+    are too old to send flushes, like the ``virtio`` driver in Linux
+    kernels older than 2.6.32.
   default: true
   services:
   - rbd
@@ -126,28 +133,40 @@ options:
   type: size
   level: advanced
   desc: cache size in bytes
+  fmt_desc: The per-volume RBD client cache size in bytes.
   default: 32_M
+  policies: write-back and write-through
   services:
   - rbd
 - name: rbd_cache_max_dirty
   type: size
   level: advanced
   desc: dirty limit in bytes - set to 0 for write-through caching
+  fmt_desc: The ``dirty`` limit in bytes at which the cache triggers write-back.
+    If ``0``, uses write-through caching.
   default: 24_M
+  constraint: Must be less than ``rbd_cache_size``.
+  policies: write-around and write-back
   services:
   - rbd
 - name: rbd_cache_target_dirty
   type: size
   level: advanced
   desc: target dirty limit in bytes
+  fmt_desc: The ``dirty target`` before the cache begins writing data to the data
+    storage. Does not block writes to the cache.
   default: 16_M
+  constraint: Must be less than ``rbd_cache_max_dirty``.
+  policies: write-back
   services:
   - rbd
 - name: rbd_cache_max_dirty_age
   type: float
   level: advanced
   desc: seconds in cache before writeback starts
+  fmt_desc: The number of seconds dirty data is in the cache before writeback starts.
   default: 1
+  policies: write-back
   services:
   - rbd
 - name: rbd_cache_max_dirty_object
@@ -230,6 +249,7 @@ options:
   type: size
   level: advanced
   desc: set to 0 to disable readahead
+  fmt_desc: Maximum size of a read-ahead request.  If zero, read-ahead is disabled.
   default: 512_K
   services:
   - rbd
@@ -237,6 +257,10 @@ options:
   type: size
   level: advanced
   desc: how many bytes are read in total before readahead is disabled
+  fmt_desc: After this many bytes have been read from an RBD image, read-ahead
+    is disabled for that image until it is closed.  This allows the
+    guest OS to take over read-ahead once it is booted.  If zero,
+    read-ahead stays enabled.
   default: 50_M
   services:
   - rbd
@@ -307,6 +331,11 @@ options:
   type: str
   level: basic
   desc: Compression hint to send to the OSDs during writes
+  fmt_desc: Hint to send to the OSDs on write operations. If set to
+    ``compressible`` and the OSD ``bluestore_compression_mode``
+    setting is ``passive``, the OSD will attempt to compress data.
+    If set to ``incompressible`` and the OSD compression setting
+    is ``aggressive``, the OSD will not attempt to compress data.
   default: none
   services:
   - rbd
@@ -320,6 +349,15 @@ options:
   type: str
   level: basic
   desc: Read replica policy send to the OSDS during reads
+  fmt_desc: |
+    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
+    as determined by the CRUSH map. Note: this feature requires the
+    cluster to be configured with a minimum compatible OSD release of
+    Octopus.
   default: default
   services:
   - rbd