From b4b7161a1208e64ca879d4b041bd81daa6b6e7ba Mon Sep 17 00:00:00 2001
From: Yin Congmin <congmin.yin@intel.com>
Date: Fri, 25 Dec 2020 22:24:33 +0800
Subject: [PATCH] doc/rbd: add the configuration description of immutable
 object cache throttle

Signed-off-by: Yin Congmin <congmin.yin@intel.com>
---
 doc/rbd/rbd-persistent-read-only-cache.rst | 104 +++++++++++++++++++--
 1 file changed, 96 insertions(+), 8 deletions(-)

diff --git a/doc/rbd/rbd-persistent-read-only-cache.rst b/doc/rbd/rbd-persistent-read-only-cache.rst
index 5bc06d3b1855c..dbaa66035e3d6 100644
--- a/doc/rbd/rbd-persistent-read-only-cache.rst
+++ b/doc/rbd/rbd-persistent-read-only-cache.rst
@@ -46,6 +46,9 @@ need to added in the ``[client]`` `section`_ of your ``ceph.conf`` file::
 Immutable Object Cache Daemon
 =============================
 
+Introduction and Generic Settings
+---------------------------------
+
 The ``ceph-immutable-object-cache`` daemon is responsible for caching parent
 image content within its local caching directory. For better performance it's
 recommended to use SSDs as the underlying storage.
@@ -73,17 +76,39 @@ capacity pressure it will evict cold cache files as needed.
 
 Here are some important cache configuration settings:
 
-- ``immutable_object_cache_sock`` The path to the domain socket used for
-  communication between librbd clients and the ceph-immutable-object-cache
-  daemon.
+``immutable_object_cache_sock``
+
+:Description: The path to the domain socket used for communication between
+              librbd clients and the ceph-immutable-object-cache daemon.
+:Type: String
+:Required: No
+:Default: ``/var/run/ceph/immutable_object_cache_sock``
+
+
+``immutable_object_cache_path``
+
+:Description: The immutable object cache data directory.
+:Type: String
+:Required: No
+:Default: ``/tmp/ceph_immutable_object_cache``
+
+
+``immutable_object_cache_max_size``
+
+:Description: The max size for immutable cache.
+:Type: Size
+:Required: No
+:Default: ``1G``
 
-- ``immutable_object_cache_path`` The immutable object cache data directory.
 
-- ``immutable_object_cache_max_size`` The max size for immutable cache.
+``immutable_object_cache_watermark``
 
-- ``immutable_object_cache_watermark`` The high-water mark for the cache. If the
-  capacity reaches this threshold the daemon will delete cold cache based
-  on LRU statistics.
+:Description: The high-water mark for the cache. The value is between (0, 1).
+              If the cache size reaches this threshold the daemon will start
+              to delete cold cache based on LRU statistics.
+:Type: Float
+:Required: No
+:Default: ``0.9``
 
 The ``ceph-immutable-object-cache`` daemon is available within the optional
 ``ceph-immutable-object-cache`` distribution package.
@@ -91,6 +116,9 @@ The ``ceph-immutable-object-cache`` daemon is available within the optional
 .. important:: ``ceph-immutable-object-cache`` daemon requires the ability to
    connect RADOS clusters.
 
+Run Daemon
+----------
+
 ``ceph-immutable-object-cache`` daemon should use a unique Ceph user ID.
 To `create a Ceph user`_, with ``ceph`` specify the ``auth get-or-create``
 command, user name, monitor caps, and OSD caps::
@@ -106,6 +134,66 @@ The ``ceph-immutable-object-cache`` can also be run in foreground by ``ceph-immu
 
   ceph-immutable-object-cache -f --log-file={log_path}
 
+QOS Settings
+------------
+
+Immutable object cache supports throttle, controlled by the following settings.
+
+``immutable_object_cache_qos_schedule_tick_min``
+
+:Description: Minimum schedule tick for immutable object cache.
+:Type: Milliseconds
+:Required: No
+:Default: ``50``
+
+
+``immutable_object_cache_qos_iops_limit``
+
+:Description: The desired immutable object cache IO operations limit per second.
+:Type: Unsigned Integer
+:Required: No
+:Default: ``0``
+
+
+``immutable_object_cache_qos_iops_burst``
+
+:Description: The desired burst limit of immutable object cache IO operations.
+:Type: Unsigned Integer
+:Required: No
+:Default: ``0``
+
+
+``immutable_object_cache_qos_iops_burst_seconds``
+
+:Description: The desired burst duration in seconds of immutable object cache IO operations.
+:Type: Seconds
+:Required: No
+:Default: ``1``
+
+
+``immutable_object_cache_qos_bps_limit``
+
+:Description: The desired immutable object cache IO bytes limit per second.
+:Type: Unsigned Integer
+:Required: No
+:Default: ``0``
+
+
+``immutable_object_cache_qos_bps_burst``
+
+:Description: The desired burst limit of immutable object cache IO bytes.
+:Type: Unsigned Integer
+:Required: No
+:Default: ``0``
+
+
+``immutable_object_cache_qos_bps_burst_seconds``
+
+:Description: The desired burst duration in seconds of immutable object cache IO bytes.
+:Type: Seconds
+:Required: No
+:Default: ``1``
+
 .. _Cloned RBD Images: ../rbd-snapshot/#layering
 .. _section: ../../rados/configuration/ceph-conf/#configuration-sections
 .. _create a Ceph user: ../../rados/operations/user-management#add-a-user
-- 
2.39.5