From: Kefu Chai Date: Mon, 10 May 2021 12:56:15 +0000 (+0800) Subject: doc/rbd/rbd-config-ref: use confval directive to define options X-Git-Tag: v17.1.0~2002^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=50c15dd7f088e2ed121f374de08c748bd6b8a1cb;p=ceph.git 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 --- diff --git a/doc/rbd/rbd-config-ref.rst b/doc/rbd/rbd-config-ref.rst index 777894cd6c39..2e391a217ca7 100644 --- 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 871f508d824a..e99cab3d2cf2 100644 --- 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