doc: Add BlueStore sharding documentation

Provide sharding explanation, configuration parameters explanation.
Provide resharding tool example into Pacific format.

Signed-off-by: Adam Kupczyk <akupczyk@redhat.com>
Co-authored-by: Josh Durgin <jdurgin@redhat.com>

diff --git a/doc/rados/configuration/bluestore-config-ref.rst b/doc/rados/configuration/bluestore-config-ref.rst
index 5cd9a16a412df7890584e8746142bf597a364880..c4a9aa48224d06d887a469b53578988f656aee5c 100644 (file)
--- a/doc/rados/configuration/bluestore-config-ref.rst
+++ b/doc/rados/configuration/bluestore-config-ref.rst
@@ -503,6 +503,50 @@ set with::
 :Required: No
 :Default: 64K
 
+.. _bluestore-rocksdb-sharding:
+
+RocksDB Sharding
+================
+
+Internally BlueStore uses multiple types of key-value data,
+stored in RocksDB.  Each data type in BlueStore is assigned a
+unique prefix. Until Pacific all key-value data was stored in
+single RocksDB column family: 'default'.  Since Pacific,
+BlueStore can divide this data into multiple RocksDB column
+families. When keys have similar access frequency, modification
+frequency and lifetime, BlueStore benefits from better caching
+and more precise compaction. This improves performance, and also
+requires less disk space during compaction, since each column
+family is smaller and can compact independent of others.
+
+OSDs deployed in Pacific or later use RocksDB sharding by default.
+If Ceph is upgraded to Pacific from a previous version, sharding is off.
+
+To enable sharding and apply the Pacific defaults, stop an OSD and run::
+
+    .. prompt:: bash #
+
+      ceph-bluestore-tool --path <data path> --sharding="m(3) p(3,0-12) O(3,0-13)=block_cache={type=binned_lru} L P" reshard
+
+``bluestore_rocksdb_cf``
+
+:Description: Enables sharding of BlueStore's RocksDB.
+             When ``true``, ``bluestore_rocksdb_cfs`` is used.
+             Only applied when OSD is doing ``--mkfs``.
+:Type: Boolean
+:Required: No
+:Default: ``True``
+
+``bluestore_rocksdb_cfs``
+
+:Description: Definition of BlueStore's RocksDB sharding.
+             The optimal value depends on multiple factors, and modification is invadvisable.
+             This setting is used only when OSD is doing ``--mkfs``.
+             Next runs of OSD retrieve sharding from disk.
+:Type: String
+:Required: No
+:Default: ``m(3) p(3,0-12) O(3,0-13)=block_cache={type=binned_lru} L P``
+
 SPDK Usage
 ==================
 

diff --git a/doc/releases/pacific.rst b/doc/releases/pacific.rst
index 8d831a9001cec265d677d53bfa9a7f28808b5c9e..9207f50aa0b1ac54777bce10f74157cf770f2af2 100644 (file)
--- a/doc/releases/pacific.rst
+++ b/doc/releases/pacific.rst
@@ -101,7 +101,7 @@ The :ref:`mgr-dashboard` brings improvements in the following management areas:
 RADOS
 ~~~~~
 
-* Pacific introduces RocksDB sharding, which reduces disk space requirements.
+* Pacific introduces :ref:`bluestore-rocksdb-sharding`, which reduces disk space requirements.
 
 * Ceph now provides QoS between client I/O and background operations via the
   mclock scheduler.