doc/ceph-volume: refine encryption.rst

Improve the word choice and grammar of
doc/ceph-volume/lvm/encryption.rst.

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

diff --git a/doc/ceph-volume/lvm/encryption.rst b/doc/ceph-volume/lvm/encryption.rst
index 4f6c80b367556de4904b66fd97b95458eb2f0ef7..66f4ee182b16055c7d08413bad19cb70215d5f97 100644 (file)
--- a/doc/ceph-volume/lvm/encryption.rst
+++ b/doc/ceph-volume/lvm/encryption.rst
@@ -4,42 +4,41 @@ Encryption
 ==========
 
 Logical volumes can be encrypted using ``dmcrypt`` by specifying the
-``--dmcrypt`` flag when creating OSDs. Encryption can be done in different ways,
-specially with LVM. ``ceph-volume`` is somewhat opinionated with the way it
-sets up encryption with logical volumes so that the process is consistent and
+``--dmcrypt`` flag when creating OSDs. When using LVM, logical volumes can be
+encrypted in different ways. ``ceph-volume`` does not offer as many options as
+LVM does, but it encrypts logical volumes in a way that  is consistent and
 robust.
 
-In this case, ``ceph-volume lvm`` follows these constraints:
+In this case, ``ceph-volume lvm`` follows this constraint:
 
-* Logical Volumes are encrypted, while their underlying PVs (physical volumes)
-  aren't
-* Non-LVM devices like partitions are also encrypted with the same OSD key
+* Non-LVM devices (such as partitions) are encrypted with the same OSD key.
 
 
 LUKS
 ----
-There are currently two versions of LUKS, 1 and 2. Version 2 is a bit easier
-to implement but not widely available in all distros Ceph supports. 
+There are currently two versions of LUKS, 1 and 2. Version 2 is a bit easier to
+implement but not widely available in all Linux distributions supported by
+Ceph. 
 
-.. note:: Version 1 of LUKS is just referenced as "LUKS" whereas version 2 is
-          referred to as LUKS2
+.. note:: Version 1 of LUKS is referred to in this documentation as "LUKS".
+   Version 2 is of LUKS is referred to in this documentation as "LUKS2".
 
 
 LUKS on LVM
 -----------
-Encryption is done on top of existing logical volumes (unlike encrypting the
-physical device). Any single logical volume can be encrypted while other
-volumes can remain unencrypted. This method also allows for flexible logical
+Encryption is done on top of existing logical volumes (this is not the same as
+encrypting the physical device). Any single logical volume can be encrypted,
+leaving other volumes unencrypted. This method also allows for flexible logical
 volume setups, since encryption will happen once the LV is created.
 
 
 Workflow
 --------
-When setting up the OSD, a secret key will be created, that will be passed
-along to the monitor in JSON format as ``stdin`` to prevent the key from being
+When setting up the OSD, a secret key is created. That secret key is passed
+to the monitor in JSON format as ``stdin`` to prevent the key from being
 captured in the logs.
 
-The JSON payload looks something like::
+The JSON payload looks something like this::
 
         {
             "cephx_secret": CEPHX_SECRET,
@@ -48,36 +47,38 @@ The JSON payload looks something like::
         }
 
 The naming convention for the keys is **strict**, and they are named like that
-for the hardcoded (legacy) names ceph-disk used.
+for the hardcoded (legacy) names used by ceph-disk.
 
 * ``cephx_secret`` : The cephx key used to authenticate
 * ``dmcrypt_key`` : The secret (or private) key to unlock encrypted devices
 * ``cephx_lockbox_secret`` : The authentication key used to retrieve the
   ``dmcrypt_key``. It is named *lockbox* because ceph-disk used to have an
-  unencrypted partition named after it, used to store public keys and other
-  OSD metadata.
+  unencrypted partition named after it, which was used to store public keys and
+  other OSD metadata.
 
 The naming convention is strict because Monitors supported the naming
-convention by ceph-disk, which used these key names. In order to keep
-compatibility and prevent ceph-disk from breaking, ceph-volume will use the same
-naming convention *although they don't make sense for the new encryption
+convention of ceph-disk, which used these key names. In order to maintain 
+compatibility and prevent ceph-disk from breaking, ceph-volume uses the same
+naming convention *although it does not make sense for the new encryption
 workflow*.
 
-After the common steps of setting up the OSD during the prepare stage, either
-with :term:`filestore` or :term:`bluestore`, the logical volume is left ready
-to be activated, regardless of the state of the device (encrypted or decrypted).
+After the common steps of setting up the OSD during the "prepare stage" (either
+with :term:`filestore` or :term:`bluestore`), the logical volume is left ready
+to be activated, regardless of the state of the device (encrypted or
+decrypted).
 
-At activation time, the logical volume will get decrypted and the OSD started
-once the process completes correctly.
+At the time of its activation, the logical volume is decrypted. The OSD starts
+after the process completes correctly.
 
-Summary of the encryption workflow for creating a new OSD:
+Summary of the encryption workflow for creating a new OSD
+----------------------------------------------------------
 
-#. OSD is created, both lockbox and dmcrypt keys are created, and sent along
-   with JSON to the monitors, indicating an encrypted OSD.
+#. OSD is created. Both lockbox and dmcrypt keys are created and sent to the
+   monitors in JSON format, indicating an encrypted OSD.
 
 #. All complementary devices (like journal, db, or wal) get created and
    encrypted with the same OSD key. Key is stored in the LVM metadata of the
-   OSD
+   OSD.
 
 #. Activation continues by ensuring devices are mounted, retrieving the dmcrypt
-   secret key from the monitors and decrypting before the OSD gets started.
+   secret key from the monitors, and decrypting before the OSD gets started.