diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10b019ce..abfa097f 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/README.md b/README.md index 7ebd7d62..0466ecd8 100644 --- a/README.md +++ b/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) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index f7bd7fd7..464f3b42 100644 --- a/docs/.custom_wordlist.txt +++ b/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 + diff --git a/docs/how-to/client-cfg.rst b/docs/how-to/client-cfg.rst new file mode 100644 index 00000000..5a1bc128 --- /dev/null +++ b/docs/how-to/client-cfg.rst @@ -0,0 +1,116 @@ +Configure RBD client cache in MicroCeph +======================================== + +Similar to :doc:`Cluster Configs ` MicroCeph also 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 | + +---+----------------+---------+----------+ + + +