doc: document ceph-disk prepare class hierarchy

Signed-off-by: Loic Dachary <loic@dachary.org>

diff --git a/doc/dev/ceph-disk.rst b/doc/dev/ceph-disk.rst
index a4008aa05fca1dc7877a91258596dcd9868ab166..3f4520ac388c3fe8b15346f5e3b5b36ad57e1677 100644 (file)
--- a/doc/dev/ceph-disk.rst
+++ b/doc/dev/ceph-disk.rst
@@ -59,3 +59,74 @@ partitions
 3. block.db for BlueStore, if co-located with data
 4. block.wal for BlueStore, if co-located with data
 5. lockbox
+
+prepare class hierarchy
+=======================
+
+The ``ceph-disk`` prepare class hierarchy can be challenging to read
+and this guide is designed to explain how it is structured.
+
+The Prepare class roughly replaces the prepare_main function but also
+handles the prepare subcommand argument parsing. It creates the data
+and journal objects and delegate the actual work to them via the
+prepare() method.
+
+The Prepare class assumes that preparing an OSD consists on the
+following phases:
+
+* optionally prepare auxiliary devices, such as the journal
+* prepare a data directory or device
+* populate the data directory with fsid etc. and optionally symbolic
+  links to the auxiliary devices
+
+The PrepareDefault class is derived from Prepare and implements the
+current model where there only is one auxiliary device, the journal.
+
+The PrepareJournal class implements the *journal* functions and is
+based on a generic class, PrepareSpace which handles the allocation of
+an auxiliary device. The only journal specific feature is left to the
+PrepareJournal class: querying the OSD to figure out if a journal is
+wanted or not.
+
+The OSD data directory is prepared via the PrepareData class. It
+creates a file system if necessary (i.e. if a device) and populate the
+data directory. Further preparation is then delegated to the auxiliary
+devices (i.e. adding a symlink to the device for a journal).
+
+There was some code paths related dmcrypt / multipath devices in the
+prepare functions, although it is orthogonal. A class tree for Devices
+was created to isolate that.
+
+Although that was the primary reason for adding a new class tree, two
+other aspects have also been moved there: ``ptypes`` (i.e. partition
+types) and partition creation.  The ``ptypes`` are organized into a data
+structure with a few helpers in the hope it will be easier to
+maintain. All references to the ``*_UUID`` variables have been
+updated.
+
+The creation of a partition is delegated to sgdisk and a wrapper helps
+reduce the code redundancy.
+
+The ``ptype`` of a given partition depends on the type of the device (is
+it dmcrypt'ed or a multipath device ?). It is best implemented by
+derivation so the prepare function does not need to be concerned about
+how the ``ptype`` of a partition is determined.
+
+Many functions could be refactored into a Device class and its
+derivatives, but that was not done to minimize the size of the
+refactor.
+
+* ``Device`` knows how to create a partition and figure out the ``ptype`` ``tobe``
+* ``DevicePartition`` a regular device partition
+* ``DevicePartitionMultipath`` a partition of a multipath device
+* ``DevicePartitionCrypt`` base class for luks/plain dmcrypt, can map/unmap
+* ``DevicePartitionCryptPlain`` knows how to setup dmcrypt plain
+* ``DevicePartitionCryptLuks`` knows how to setup dmcrypt luks
+
+The CryptHelpers class is introduced to factorize the code snippets
+that were duplicated in various places but that do not really belong
+because they are convenience wrappers to figure out:
+
+* if dcmrypt should be used
+* the keysize
+* the dmcrypt type (plain or luks)