diff --git a/doc/source/admin/cleaning.rst b/doc/source/admin/cleaning.rst
index a3d8e9e83c..04e84617d1 100644
--- a/doc/source/admin/cleaning.rst
+++ b/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
-will fall back to using ``shred`` to overwrite the contents of the device.
-Otherwise cleaning will fail. It is important to note that ``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.
-Generally, it is very difficult (if possible at all) to recover data after
-performing cleaning with ``erase_devices``.
+:oslo.config:option:`deploy.continue_if_disk_secure_erase_fails` is set to
+``True``, cleaning will fall back to using ``shred`` to overwrite the
+contents of the device. By default, if ``erase_devices`` is enabled
+and Ironic is unable to erase the device, cleaning will fail to ensure
+data security.
+
+.. 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.
-``erase_devices_express`` is disabled by default. In order to use it, the
-following configuration is recommended.
+erasure of data on commodity HDDs.
+
+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]/erase_devices_metadata_priority=0
- [conductor]/clean_step_priority_override=deploy.erase_devices_express:5
+ [deploy]
+ erase_devices_priority=0
+ 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
-default).
+Other configurations that can modify how Ironic erases disks are below.
+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
-``erase_devices``, which can have its priority set in ironic.conf. For instance,
-to disable erase_devices, you'd set the following configuration option::
-
- [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:
+requires use of :oslo.config:option:`conductor.clean_step_priority_override`,
+a configuration option which allows specifying priority of each step using
+multiple configuration values:
.. code-block:: ini