Add detailed information about cleaning

Change-Id: I9aa1b65cd87811ba3624ee31add2771d8c12f02d

doc/source/install/advanced_deployment/baremetal_nodes.rst

@@ -7,6 +7,7 @@ Documentation on how to do advanced configuration of baremetal nodes in
 .. toctree::
 
    node_states
+   cleaning
    node_discovery
    root_device
    introspect_single_node

doc/source/install/advanced_deployment/cleaning.rst

@@ -0,0 +1,62 @@
+Node cleaning
+=============
+
+In Ironic *cleaning* is a process of preparing a bare metal node for
+provisioning. There are two types of cleaning: *automated* and *manual*.
+See `cleaning documentation
+<https://docs.openstack.org/ironic/latest/admin/cleaning.html>`_ for more
+details.
+
+.. warning::
+   It is highly recommended to at least wipe metadata (partitions and
+   partition table(s)) from all disks before deployment.
+
+Automated cleaning
+------------------
+
+*Automated cleaning* runs before a node gets to the ``available`` state (see
+:doc:`node_states` for more information on provisioning states). It happens
+after the first enrollment and after every unprovisioning.
+
+In the TripleO undercloud automated cleaning is **disabled** by default.
+Starting with the Ocata release, it can be enabled by setting the following
+option in your ``undercloud.conf``:
+
+.. code-block:: ini
+
+  [DEFAULT]
+  clean_nodes = True
+
+Alternatively, you can use `Manual cleaning`_ as described below.
+
+Manual cleaning
+---------------
+
+*Manual cleaning* is run on request for nodes in the ``manageable`` state.
+
+If you have *automated cleaning* disabled, you can use the following procedure
+to wipe the node's metadata starting with the Rocky release:
+
+#. If the node is not in the ``manageable`` state, move it there::
+
+    openstack baremetal node manage <UUID or name>
+
+#. Run manual cleaning on a specific node::
+
+    openstack overcloud node clean <UUID or name>
+
+   or all manageable nodes::
+
+    openstack overcloud node clean --all-manageable
+
+#. Make the node available again::
+
+    openstack overcloud node provide <UUID or name>
+
+   or provide all manageable nodes::
+
+    openstack overcloud node provide --all-manageable
+
+See :ref:`cleaning_workflow` for an explanation how to use Mistral workflows
+directly to initiate cleaning. This is particularly useful if you want to run
+some non-standard clean steps.

doc/source/install/basic_deployment/basic_deployment_cli.rst

@@ -294,6 +294,10 @@ as a root device. Please see :ref:`root_device` for details.
    across rebuilds. Make sure to wipe the previous installation before
    rebuilding in this case.
 
+If there is information from previous deployments on the nodes' disks, it is
+recommended to at least remove the partitions and partition table(s). See
+:doc:`../advanced_deployment/cleaning` for information on how to do it.
+
 Finally, if you want your nodes to boot in the UEFI mode, additional steps may
 have to be taken - see :doc:`../advanced_deployment/uefi_boot` for details.
 
@@ -638,8 +642,7 @@ The overcloud can be redeployed when desired.
     openstack stack list
 
 #. It is recommended that you delete existing partitions from all nodes before
-   redeploying. Starting with TripleO Ocata, you can use existing workflows -
-   see :ref:`cleaning` for details.
+   redeploying, see :doc:`../advanced_deployment/cleaning` for details.
 
 #. Deploy the Overcloud again::
 

doc/source/install/mistral-api/mistral-api.rst

@@ -260,7 +260,7 @@ nodes to be in the "manageable" state.
     $ openstack workflow execution create tripleo.baremetal.v1.introspect \
         '{"nodes_uuids": ["UUID1", "UUID2"]}'
 
-.. _cleaning:
+.. _cleaning_workflow:
 
 Cleaning Nodes
 ^^^^^^^^^^^^^^