Document the use of external Ceph journal drives

Change-Id: I3f0873f425f49514e6f086a6baa25dc3a3ee1dd5
Closes-bug: #1560049

1 files changed, 48 insertions, 2 deletions

diff --git a/doc/ceph-guide.rst b/doc/ceph-guide.rst
index 1f892e13b..2be412ae5 100644
--- a/doc/ceph-guide.rst
+++ b/doc/ceph-guide.rst
@@ -15,8 +15,8 @@ Requirements
 * A minimum of 3 hosts for a vanilla deploy
 * A minimum of 1 block device per host
 
-Preparation and Deployment
-==========================
+Preparation
+===========
 
 To prepare a disk for use as a
 `Ceph OSD <http://docs.ceph.com/docs/master/man/8/ceph-osd/>`_ you must add a
@@ -47,6 +47,49 @@ usage with Kolla.
          1      1049kB  10.7GB  10.7GB               KOLLA_CEPH_OSD_BOOTSTRAP
 
 
+Using an external journal drive
+-------------------------------
+
+The steps documented above created a journal partition of 5 GByte
+and a data partition with the remaining storage capacity on the same tagged
+drive.
+
+It is a common practice to place the journal of an OSD on a separate
+journal drive. This section documents how to use an external journal drive.
+
+Prepare the storage drive in the same way as documented above:
+
+::
+
+    # <WARNING ALL DATA ON $DISK will be LOST!>
+    # where $DISK is /dev/sdb or something similar
+    parted $DISK -s -- mklabel gpt mkpart KOLLA_CEPH_OSD_BOOTSTRAP_FOO 1 -1
+
+To prepare the journal external drive execute the following command:
+
+::
+
+    # <WARNING ALL DATA ON $DISK will be LOST!>
+    # where $DISK is /dev/sdc or something similar
+    parted $DISK -s -- mklabel gpt mkpart KOLLA_CEPH_OSD_BOOTSTRAP_FOO_J 1 -1
+
+.. note::
+
+   Use different suffixes (``_42``, ``_FOO``, ``_FOO42``, ..) to use different external
+   journal drives for different storage drives. One external journal drive can only
+   be used for one storage drive.
+
+.. note::
+
+   The partition labels ``KOLLA_CEPH_OSD_BOOTSTRAP`` and ``KOLLA_CEPH_OSD_BOOTSTRAP_J``
+   are not working when using external journal drives. It is required to use
+   suffixes (``_42``, ``_FOO``, ``_FOO42``, ..). If you want to setup only one
+   storage drive with one external journal drive it is also necessary to use a suffix.
+
+
+Configuration
+=============
+
 Edit the [storage] group in the inventory which contains the hostname of the
 hosts that have the block devices you have prepped as shown above.
 
@@ -82,6 +125,9 @@ and add the contents::
     osd pool default min size = 1
 
 
+Deployment
+==========
+
 Finally deploy the Ceph-enabled OpenStack:
 
 ::