doc/cephadm: rewrite part of "deploy osds"

This reorganizes the section "Deploy OSDs"
in the "OSD Service" chapter of the Cephadm
Guide. Two new sections, "Listing Storage
Devices" and "Creating New OSDs" gather
information under headings in a sensible way,
making the information more accessible to someone
skimming this Guide.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
(cherry picked from commit 5f1ce2f6e8df185673613df9a31bac2395a46438)

diff --git a/doc/cephadm/osd.rst b/doc/cephadm/osd.rst
index 93e229fd40f93167adb5376d254e903fa1c3b9ce..adf44d182e1ee7111be623f5978ee5a304e2b790 100644 (file)
--- a/doc/cephadm/osd.rst
+++ b/doc/cephadm/osd.rst
@@ -91,7 +91,13 @@ information about interacting with these LEDs, refer to `device management`_.
 Deploy OSDs
 ===========
 
-An inventory of storage devices on all cluster hosts can be displayed with:
+Listing Storage Devices
+-----------------------
+
+In order to deploy an OSD, there must be a storage device that is *available* on
+which the OSD will be deployed.
+
+Run this command to display an inventory of storage devices on all cluster hosts:
 
 .. prompt:: bash #
 
@@ -107,7 +113,10 @@ conditions are met:
 * The device must not contain a Ceph BlueStore OSD.
 * The device must be larger than 5 GB.
 
-Ceph refuses to provision an OSD on a device that is not available.
+Ceph will not provision an OSD on a device that is not available.
+
+Creating New OSDs
+-----------------
 
 There are a few ways to create new OSDs:
 
@@ -129,9 +138,10 @@ There are a few ways to create new OSDs:
 
     ceph orch daemon add osd host1:/dev/sdb
 
-* Use :ref:`drivegroups` to describe device(s) to consume
-  based on their properties, such device type (SSD or HDD), device
-  model names, size, or the hosts on which the devices exist:
+* You can use :ref:`drivegroups` to categorize device(s) based on their
+  properties. This might be useful in forming a clearer picture of which
+  devices are available to consume. Properties include device type (SSD or
+  HDD), device model names, size, and the hosts on which the devices exist:
 
   .. prompt:: bash #