Doc: loop file backed OSDs

Signed-off-by: Peter Sabaini <[email protected]>
sabaini · Nov 24, 2023 · 6d8fe0a · 6d8fe0a
1 parent 8944311
commit 6d8fe0a
Show file tree

Hide file tree

Showing 3 changed files with 40 additions and 44 deletions.
diff --git a/docs/reference/commands/disk.rst b/docs/reference/commands/disk.rst
@@ -33,13 +33,27 @@ Global flags:
 ``add``
 -------
 
-Adds a disk to the cluster, alongside optional devices for write-ahead logging and database management.
+Adds a new Ceph disk (OSD) to the cluster, alongside optional devices for write-ahead logging and database management.
+
+The command takes a parameter SPEC which is either a path to a block device such as /dev/sdb or a specification for one or more loop files.
+
+The specification for loop files is of the form "loop,<size>,<nr>"
+
+- size is a number with M, G, or T suffixes for megabytes, gigabytes, or terabytes.
+- nr is the number of file-backed loop OSDs to create.
+
+For instance, a spec of `loop,8G,3` will create 3 file-backed loop OSDs of 8GB each.
+
+While loop files provide a convenient way to quickly set up small test and development clusters, for
+production deployments it is **strongly** recommended to use dedicated block devices for safety and
+performance reasons.
+
 
 Usage:
 
 .. code-block:: none
 
-   microceph disk add <PATH> [flags]
+   microceph disk add <SPEC> [flags]
 
 Flags:
 
@@ -48,7 +62,7 @@ Flags:
    --db-device string    The device used for the DB
    --db-encrypt          Encrypt the DB device prior to use
    --db-wipe             Wipe the DB device prior to use
-   --encrypt             Encrypt the disk prior to use
+   --encrypt             Encrypt the disk prior to use (only block devices)
    --wal-device string   The device used for WAL
    --wal-encrypt         Encrypt the WAL device prior to use
    --wal-wipe            Wipe the WAL device prior to use
@@ -64,6 +78,10 @@ Flags:
    as long as they are faster than the data device. WAL should take priority
    over DB if there isn't enough storage for both.
 
+   WAL and DB devices can only be used with data devices that reside on a
+   block device, not with loop files. Loop files do not support encryption.
+
+
 ``list``
 --------
 

diff --git a/docs/tutorial/multi-node.rst b/docs/tutorial/multi-node.rst
@@ -2,8 +2,9 @@
 Multi-node install
 ==================
 
-This tutorial will show how to install MicroCeph on three machines, thereby
-creating a multi-node cluster.
+This tutorial will show how to install MicroCeph on three machines,
+thereby creating a multi-node cluster. For this tutorial, we will
+utilize physical block devices for storage.
 
 Ensure storage requirements
 ---------------------------

diff --git a/docs/tutorial/single-node.rst b/docs/tutorial/single-node.rst
@@ -5,36 +5,6 @@ Single-node install
 This tutorial will show how to install MicroCeph on a single machine, thereby
 creating a single-node "cluster".
 
-Ensure storage requirements
----------------------------
-
-Three OSDs will be required to form a minimal Ceph cluster. This means that
-three entire disks are required to be available on the machine.
-
-.. note::
-
-   Development is underway to allow for loopback device support. This will
-   allow for easier proof-of-concept and developer deployments.
-
-The disk subsystem can be inspected with the :command:`lsblk` command. In this
-tutorial, the command's output is shown below. Any output related to possible
-loopback devices has been suppressed for the purpose of clarity:
-
-.. code-block:: none
-
-   lsblk | grep -v loop
-
-   NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
-   sda           8:0    0 931.5G  0 disk
-   sdb           8:16   0 931.5G  0 disk
-   sdc           8:32   0 931.5G  0 disk
-   sdd           8:48   0 931.5G  0 disk
-   nvme0n1     259:0    0 372.6G  0 disk
-   ├─nvme0n1p1 259:1    0   512M  0 part /boot/efi
-   └─nvme0n1p2 259:2    0 372.1G  0 part /
-
-There are four disks available, here we will use disks ``/dev/sda``,
-``/dev/sdb``, and ``/dev/sdc``.
 
 Install the software
 --------------------
@@ -89,20 +59,27 @@ yet any storage available.
 Add storage
 -----------
 
-.. warning::
-
-   This step will remove the data found on the target storage disks. Make sure
-   you don't lose data unintentionally.
+Three OSDs will be required to form a minimal Ceph cluster. In a
+production system, typically we would assign one physical block device
+for an OSD. However for this tutorial, we will make use of file backed
+OSDs for simplicity. In this configuration, we won't be using real
+block devices for storage but instead simulate using regular files.
 
-Add the three disks to the cluster by using the :command:`disk add` command:
+Add the three file-backed OSDs to the cluster by using the
+:command:`disk add` command. In the example, three 4Gb files are being
+created -- adjust the size to your needs, with a recommended minimum
+of 2G per OSD:
 
 .. code-block:: none
 
-   sudo microceph disk add /dev/sda --wipe
-   sudo microceph disk add /dev/sdb --wipe
-   sudo microceph disk add /dev/sdc --wipe
+   sudo microceph disk add loop,4G,3
+
+.. warning::
 
-Adjust the above commands according to the storage disks at your disposal.
+   While loop files provide a convenient way to quickly set up small
+   test and development clusters, for production deployments it is
+   **strongly** recommended to use dedicated block devices for safety
+   and performance reasons.
 
 Recheck status: