From: Avan Thakkar Date: Mon, 4 Aug 2025 14:44:53 +0000 (+0530) Subject: doc/mgr/smb: add doc for QoS support for CephFS-backed SMB shares X-Git-Tag: testing/wip-pdonnell-testing-20260323.122957-tentacle~621 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=465d9e8a8abc3d825cdfad46c9a38317e6aaff3f;p=ceph-ci.git doc/mgr/smb: add doc for QoS support for CephFS-backed SMB shares Signed-off-by: Avan Thakkar (cherry picked from commit 83db4df25a2d29538eebda7c6efdfb4cf2aedb04) --- diff --git a/doc/mgr/smb.rst b/doc/mgr/smb.rst index a443e47409a..2270182f45d 100644 --- a/doc/mgr/smb.rst +++ b/doc/mgr/smb.rst @@ -179,6 +179,69 @@ subvolume readonly Creates a read-only share +Update Share QoS +++++++++++++++++ + +.. prompt:: bash # + + ceph smb share update cephfs qos [--read-iops-limit=] [--write-iops-limit=] [--read-bw-limit=] [--write-bw-limit=] [--read-delay-max=] [--write-delay-max=] + +Update Quality of Service (QoS) settings for a CephFS-backed share. This allows administrators to apply per-share rate limits on SMB input/output (I/O) operations, specifically limits on IOPS (Input/Output Operations per Second) and bandwidth (in bytes per second) for both read and write operations. + +Options: + +read_iops_limit + Optional integer. Maximum number of read operations per second (0 = disabled). + Valid range: ``0`` to ``1,000,000``. Values above this will be capped. +write_iops_limit + Optional integer. Maximum number of write operations per second (0 = disabled). + Valid range: ``0`` to ``1,000,000``. Values above this will be capped. +read_bw_limit + Optional integer. Maximum allowed bandwidth for read operations in bytes per second (0 = disabled). + Valid range: ``0`` to ``1 << 40`` (≈1 TB/s). Values above this will be capped. +write_bw_limit + Optional integer. Maximum allowed bandwidth for write operations in bytes per second (0 = disabled). + Valid range: ``0`` to ``1 << 40`` (≈1 TB/s). Values above this will be capped. +read_delay_max + Optional integer. Maximum allowed delay value in seconds for read operations (default: 30, max: 300). + This acts as an upper bound on how long a read request will be delayed if the defined IOPS or bandwidth limits are exceeded. +write_delay_max + Optional integer. Maximum allowed delay value in seconds for write operations (default: 30, max: 300). + Similar to `read_delay_max`, but applies to write requests. + +Behavior: + +- All limits are optional +- Setting a limit to ``0`` disables that specific QoS limit +- Setting all four limits to ``0`` completely removes QoS configuration + +Examples: + +Set QoS limits for a share: + +.. prompt:: bash # + + ceph smb share update cephfs qos foo bar \ + --read-iops-limit=100 \ + --write-iops-limit=200 \ + --read-bw-limit=1048576 \ + --write-bw-limit=2097152 \ + --read-delay-max=5 \ + --write-delay-max=5 + +Disable QoS for a share: + +.. prompt:: bash # + + ceph smb share update cephfs qos foo bar \ + --read-iops-limit=0 \ + --write-iops-limit=0 \ + --read-bw-limit=0 \ + --write-bw-limit=0 \ + --read-delay-max=0 \ + --write-delay-max=0 + + Remove Share ++++++++++++ @@ -769,6 +832,27 @@ cephfs name String. A value indicating what fscrypt key to fetch. The specific value of the name depends on the scope being used. + qos + Optional object. Quality of Service settings for the share. Fields: + + read_iops_limit + Optional integer. Maximum number of read operations per second (0 = disabled). + Valid range: ``0`` to ``1,000,000``. Values above this will be capped. + write_iops_limit + Optional integer. Maximum number of write operations per second (0 = disabled). + Valid range: ``0`` to ``1,000,000``. Values above this will be capped. + read_bw_limit + Optional integer. Maximum allowed bandwidth for read operations in bytes per second (0 = disabled). + Valid range: ``0`` to ``1 << 40`` (≈1 TB/s). Values above this will be capped. + write_bw_limit + Optional integer. Maximum allowed bandwidth for write operations in bytes per second (0 = disabled). + Valid range: ``0`` to ``1 << 40`` (≈1 TB/s). Values above this will be capped. + read_delay_max + Optional integer. Maximum allowed delay value in seconds for read operations (default: 30, max: 300). + This acts as an upper bound on how long a read request will be delayed if the defined IOPS or bandwidth limits are exceeded. + write_delay_max + Optional integer. Maximum allowed delay value in seconds for write operations (default: 30, max: 300). + Similar to `read_delay_max`, but applies to write requests. restrict_access Optional boolean, defaulting to false. If true the share will only permit access by users explicitly listed in ``login_control``. @@ -799,7 +883,7 @@ custom_smb_share_options things in ways that the Ceph team can not help with. This special key will automatically be removed from the list of options passed to Samba. -The following is an example of a share: +The following is an example of a share with QoS settings: .. code-block:: yaml @@ -812,9 +896,34 @@ The following is an example of a share: path: /pics subvolumegroup: smbshares subvolume: staff + qos: + read_iops_limit: 100 # Max 100 read operations per second + write_iops_limit: 50 # Max 50 write operations per second + read_bw_limit: 1048576 # 1 MiB/s read bandwidth limit + write_bw_limit: 524288 # 512 KiB/s write bandwidth limit + read_delay_max: 5 # Max 5 seconds delay for read operations + write_delay_max: 5 # Max 5 seconds delay for write operations + + +Another example, this time of a share with QoS disabled: +.. code-block:: yaml -Another example, this time of a share with an intent to be removed: + resource_type: ceph.smb.share + cluster_id: tango + share_id: sp2 + cephfs: + volume: cephfs + path: /data + qos: + read_iops_limit: 0 + write_iops_limit: 0 + read_bw_limit: 0 + write_bw_limit: 0 + read_delay_max: 0 + write_delay_max: 0 + +And finally, a share with an intent to be removed: .. code-block:: yaml