Deduplicate and remove invalid information for steps

Lots of references to deprecated ways of doing things, as well as two
entire separate sections dedicated to how disk erasure works.

Also ensured we reference new valid config options surrounding disk
erasure.

Additional improvments could include adding documentation around how to
skip disks per node (or linking to any preexisting docs around it).

Change-Id: Ifa029e26eff0637b443d094d85e773b885d0979b

doc/source/admin/cleaning.rst

@@ -76,6 +76,10 @@ See `How do I change the priority of a cleaning step?`_ for more information.
 Storage cleaning options
 ------------------------
 
+.. warning::
+   Ironic's storage cleaning options by default will remove data from the disk
+   permanently during automated cleaning.
+
 Clean steps specific to storage are ``erase_devices``,
 ``erase_devices_metadata`` and (added in Yoga) ``erase_devices_express``.
 
@@ -83,13 +87,16 @@ Clean steps specific to storage are ``erase_devices``,
 way available. On devices that support hardware assisted secure erasure
 (many NVMe and some ATA drives) this is the preferred option. If
 hardware-assisted secure erasure is not available and if
-``[deploy]/continue_if_disk_secure_erase_fails`` is set to ``True``, cleaning
+:oslo.config:option:`deploy.continue_if_disk_secure_erase_fails` is set to
-will fall back to using ``shred`` to overwrite the contents of the device.
+``True``, cleaning will fall back to using ``shred`` to overwrite the
-Otherwise cleaning will fail. It is important to note that ``erase_devices``
+contents of the device. By default, if ``erase_devices`` is enabled
-may take a very long time (hours or even days) to complete, unless fast,
+and Ironic is unable to erase the device, cleaning will fail to ensure
-hardware assisted data erasure is supported by all the devices in a system.
+data security.
-Generally, it is very difficult (if possible at all) to recover data after
+
-performing cleaning with ``erase_devices``.
+.. note::
+   ``erase_devices`` may take a very long time (hours or even days) to
+   complete, unless fast, hardware assisted data erasure is supported by
+   all the devices in a system.
 
 ``erase_devices_metadata`` clean step doesn't provide as strong assurance
 of irreversible destruction of data as ``erase_devices``. However, it has the
@@ -110,23 +117,53 @@ data erasure as it is possible within a short period of time.
 This clean step is particularly well suited for environments with hybrid
 NVMe-HDD storage configuration as it allows fast and secure erasure of data
 stored on NVMes combined with equally fast but more basic metadata-based
-erasure of data on HDDs.
+erasure of data on commodity HDDs.
-``erase_devices_express`` is disabled by default. In order to use it, the
+
-following configuration is recommended.
+By default, Ironic will use ``erase_devices_metadata`` early in cleaning
+for reliability (ensuring a node cannot reboot into it's old workload) and
+``erase_devices`` later in cleaning to securely erase the drive;
+``erase_devices_express`` is disabled.
+
+Operators can use :oslo.config:option:`deploy.erase_devices_priority` and
+:oslo.config:option:`deploy.erase_devices_metadata_priority` to change the
+priorities of the default device erase methods or disable them entirely
+by setting ``0``. Other cleaning steps can have their priority modified
+via the :oslo.config:option:`conductor.clean_step_priority_override` option.
+For example, the configuration snippet below disables
+``erase_devices_metadata`` and ``erase_devices`` and instead performs an
+``erase_devices_express`` erase step.
 
 .. code-block:: ini
 
-    [deploy]/erase_devices_priority=0
+    [deploy]
-    [deploy]/erase_devices_metadata_priority=0
+    erase_devices_priority=0
-    [conductor]/clean_step_priority_override=deploy.erase_devices_express:5
+    erase_devices_metadata_priority=0
+
+    [conductor]
+    clean_step_priority_override=deploy.erase_devices_express:95
 
 This ensures that ``erase_devices`` and ``erase_devices_metadata`` are
 disabled so that storage is not cleaned twice and then assigns a non-zero
 priority to ``erase_devices_express``, hence enabling it. Any non-zero
-priority specified in the priority override will work.
+priority specified in the priority override will work; larger values will
+cause the disk erasure to run earlier in the cleaning process if multiple
+steps are enabled.
 
-Also ``[deploy]/enable_nvme_secure_erase`` should not be disabled (it is on by
+Other configurations that can modify how Ironic erases disks are below.
-default).
+This list may not be comprehensive. Please review ironic.conf.sample
+(linked) for more details:
+
+* :oslo.config:option:`deploy.enable_ata_secure_erase`, default ``True``
+* :oslo.config:option:`deploy.enable_nvme_secure_erase`, default ``True``
+* :oslo.config:option:`deploy.shred_random_overwrite_iterations`, default ``1``
+* :oslo.config:option:`deploy.shred_final_overwrite_with_zeros`, default ``True``
+* :oslo.config:option:`deploy.disk_erasure_concurrency`, default ``4``
+
+.. warning::
+  Ironic automated cleaning is defaulted to a secure configuration. You should
+  not modify settings related to it unless you are have special hardware needs,
+  or a unique use case. Misconfigurations can lead to data exposure
+  vulnerabilities.
 
 .. show-steps::
    :phase: cleaning
@@ -218,7 +255,7 @@ Alternatively, you can specify a runbook instead of clean_steps::
 
 The specified runbook must match one of the node's traits to be used.
 
-Starting manual cleaning via "openstack metal" CLI
+Starting manual cleaning via "openstack baremetal" CLI
 ------------------------------------------------------
 
 Manual cleaning is available via the ``baremetal node clean``
@@ -330,6 +367,7 @@ How do I skip a cleaning step?
 ------------------------------
 For automated cleaning, cleaning steps with a priority of 0 or None are skipped.
 
+.. _clean_step_priority:
 
 How do I change the priority of a cleaning step?
 ------------------------------------------------
@@ -342,46 +380,9 @@ Most out-of-band cleaning steps have an explicit configuration option for
 priority.
 
 Changing the priority of an in-band (ironic-python-agent) cleaning step
-requires use of a custom HardwareManager. The only exception is
+requires use of :oslo.config:option:`conductor.clean_step_priority_override`,
-``erase_devices``, which can have its priority set in ironic.conf. For instance,
+a configuration option which allows specifying priority of each step using
-to disable erase_devices, you'd set the following configuration option::
+multiple configuration values:
-
-  [deploy]
-  erase_devices_priority=0
-
-To enable/disable the in-band disk erase using ``ilo`` hardware type, use the
-following configuration option::
-
-  [ilo]
-  clean_priority_erase_devices=0
-
-The generic hardware manager first identifies whether a device is an NVMe
-drive or an ATA drive so that it can attempt a platform-specific secure erase
-method. In case of NVMe drives, it tries to perform a secure format operation
-by using the ``nvme-cli`` utility. This behavior can be controlled using
-the following configuration option (by default it is set to True)::
-
-   [deploy]
-   enable_nvme_secure_erase=True
-
-
-In case of ATA drives, it tries to perform ATA disk erase by using the
-``hdparm`` utility.
-
-If neither method is supported, it performs software based disk erase using
-the ``shred`` utility.  By default, the number of iterations performed
-by ``shred`` for software based disk erase is 1. To configure the number of
-iterations, use the following configuration option::
-
-  [deploy]
-  erase_devices_iterations=1
-
-Overriding step priority
-------------------------
-
-:oslo.config:option:`conductor.clean_step_priority_override` is a new configuration option
-which allows specifying priority of each step using multiple configuration
-values:
 
 .. code-block:: ini