Adds microceph client configuration support for rbd_cache

.github/workflows/tests.yml

@@ -285,6 +285,8 @@ jobs:
         fi
         lxc exec node-head -- sh -c "microceph.ceph -s" | fgrep "mon: 3 daemons"
 
+    - name: Test client configurations
+      run: ~/actionutils.sh check_client_configs
 
   upgrade-quincy-tests:
     name: Test quincy upgrades

CONTRIBUTING.md

@@ -12,7 +12,7 @@ other projects.
 The agreement can be found, and signed, here:
 https://ubuntu.com/legal/contributors
 
-Refer to [Microceph Hacking Guide](/HACKING.md) for a basic outline of the codebase and build tools.
+Refer to [MicroCeph Hacking Guide](/HACKING.md) for a basic outline of the codebase and build tools.
 
 ## Contributor guidelines
 

README.md

@@ -142,7 +142,7 @@ $ sudo microceph.ceph status
 
 ## 👍 How Can I Contribute ?
 
-1. Checkout [Microceph Hacking Guide](/HACKING.md) to start building and contributing to the codebase.
+1. Checkout [MicroCeph Hacking Guide](/HACKING.md) to start building and contributing to the codebase.
 2. Excited about [MicroCeph](https://snapcraft.io/microceph) ? Join our [Stargazers](https://github.com/canonical/microceph/stargazers)
 3. Write reviews or tutorials to help spread the knowledge 📖
 4. Participate in [Pull Requests](https://github.com/canonical/microceph/pulls) and help fix [Issues](https://github.com/canonical/microceph/issues)

docs/.custom_wordlist.txt

@@ -1,5 +1,6 @@
 openstack
 ceph
+sudo
 Howto
 configs
 osd
@@ -9,6 +10,7 @@ cfg
 CFG
 
 MicroCeph
+microceph
 OSDs
 MSD
 Ceph
@@ -45,8 +47,15 @@ Pre
 mds
 mon
 rgw
+rbd
+RBD
 MgrReports
 scalable
 Mattermost
 integratable
 cfg
+conf
+qemu
+writethrough
+writeback
+

docs/how-to/rbd-client-cfg.rst

@@ -0,0 +1,114 @@
+Configure RBD client cache in MicroCeph
+========================================
+
+MicroCeph supports setting, resetting, and listing client configurations which are exported to ceph.conf and are used by tools like qemu directly for configuring rbd cache. Below are the supported client configurations.
+
+.. list-table:: Supported Config Keys
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Key
+     - Description
+   * - rbd_cache
+     - Enable caching for RADOS Block Device (RBD).
+   * - rbd_cache_size
+     - The RBD cache size in bytes.
+   * - rbd_cache_writethrough_until_flush
+     - The number of seconds dirty data is in the cache before writeback starts.
+   * - rbd_cache_max_dirty
+     - The dirty limit in bytes at which the cache triggers write-back. If 0, uses write-through caching.
+   * - rbd_cache_target_dirty
+     - The dirty target before the cache begins writing data to the data storage. Does not block writes to the cache.
+
+1. Supported config keys can be configured using the 'set' command:
+
+  .. code-block:: shell
+
+    $ sudo microceph client config set rbd_cache true
+    $ sudo microceph client config set rbd_cache false --target alpha
+    $ sudo microceph client config set rbd_cache_size 2048MiB --target beta
+
+  .. note::
+
+    Host level configuration changes can be made by passing the relevant hostname as the --target parameter.
+
+2. All the client configs can be queried using the 'list' command.
+
+  .. code-block:: shell
+
+    $ sudo microceph cluster config list
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | true    | beta     |
+    +---+----------------+---------+----------+
+    | 1 | rbd_cache      | false   | alpha    |
+    +---+----------------+---------+----------+
+    | 2 | rbd_cache_size | 2048MiB | beta     |
+    +---+----------------+---------+----------+
+
+  Similarly, all the client configs of a particular host can be queried using the --target parameter.
+
+  .. code-block:: shell
+
+    $ sudo microceph cluster config list --target beta
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | true    | beta     |
+    +---+----------------+---------+----------+
+    | 1 | rbd_cache_size | 2048MiB | beta     |
+    +---+----------------+---------+----------+
+
+
+3. A particular config key can be queried for using the 'get' command:
+
+  .. code-block:: shell
+
+    $ sudo microceph cluster config list
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | true    | beta     |
+    +---+----------------+---------+----------+
+    | 1 | rbd_cache      | false   | alpha    |
+    +---+----------------+---------+----------+
+
+  Similarly, --target parameter can be used with get command to query for a particular config key/hostname pair.
+
+  .. code-block:: shell
+
+    $ sudo microceph cluster config rbd_cache --target alpha
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | false   | alpha    |
+    +---+----------------+---------+----------+
+
+
+4. Resetting a config key (i.e. removing the configured key/value) can performed using the 'reset' command:
+
+  .. code-block:: shell
+
+   $ sudo microceph cluster config reset rbd_cache_size
+   $ sudo microceph cluster config list
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | true    | beta     |
+    +---+----------------+---------+----------+
+    | 1 | rbd_cache      | false   | alpha    |
+    +---+----------------+---------+----------+
+
+  This operation can also be performed for a specific host as follows:
+
+  .. code-block:: shell
+
+   $ sudo microceph cluster config reset rbd_cache --target alpha
+   $ sudo microceph cluster config list
+    +---+----------------+---------+----------+
+    | # |      KEY       |  VALUE  |   HOST   |
+    +---+----------------+---------+----------+
+    | 0 | rbd_cache      | true    | beta     |
+    +---+----------------+---------+----------+
+

docs/reference/commands/client.rst

@@ -0,0 +1,121 @@
+===========
+``client``
+===========
+
+Manages MicroCeph clients
+
+Usage:
+
+.. code-block:: none
+
+   microceph client [flags]
+   microceph client [command]
+
+Available commands:
+
+.. code-block:: none
+
+   config      Manage Ceph Client configs
+
+Global options:
+
+.. code-block:: none
+
+   -d, --debug       Show all debug messages
+   -h, --help        Print help
+       --state-dir   Path to store state information
+   -v, --verbose     Show all information messages
+       --version     Print version number
+
+``config``
+----------
+
+Manages Ceph Cluster configs.
+
+Usage:
+
+.. code-block:: none
+
+   microceph cluster config [flags]
+   microceph cluster config [command]
+
+Available Commands:
+
+.. code-block:: none
+
+   get         Fetches specified Ceph Client config
+   list        Lists all configured Ceph Client configs
+   reset       Removes specified Ceph Client configs
+   set         Sets specified Ceph Client config
+
+``config set``
+--------------
+
+Sets specified Ceph Client config
+
+Usage:
+
+.. code-block:: none
+
+   microceph client config set <Key> <Value> [flags]
+
+Flags:
+
+.. code-block:: none
+
+   --target string   Specify a microceph node the provided config should be applied to. (default "*")
+   --wait            Wait for configs to propagate across the cluster. (default true)
+
+``config get``
+--------------
+
+Fetches specified Ceph Client config
+
+Usage:
+
+.. code-block:: none
+
+   microceph client config get <key> [flags]
+
+Flags:
+
+.. code-block:: none
+
+   --target string   Specify a microceph node the provided config should be applied to. (default "*")
+
+``config list``
+---------------
+
+Lists all configured Ceph Client configs
+
+Usage:
+
+.. code-block:: none
+
+   microceph client config list [flags]
+
+Flags:
+
+.. code-block:: none
+
+   --target string   Specify a microceph node the provided config should be applied to. (default "*")
+
+``config reset``
+----------------
+
+Removes specified Ceph Client configs
+
+Usage:
+
+.. code-block:: none
+
+   microceph client config reset <key> [flags]
+
+Flags:
+
+.. code-block:: none
+
+   --target string          Specify a microceph node the provided config should be applied to. (default "*")
+   --wait                   Wait for required ceph services to restart post config reset. (default true)
+   --yes-i-really-mean-it   Force microceph to reset all client config records for given key.
+