From 03d9dec4e4d94b598d54dd6a0d1b22d8be40b597 Mon Sep 17 00:00:00 2001
From: Josh Gachnang <josh@pcsforeducation.com>
Date: Thu, 16 Apr 2015 16:49:33 -0500
Subject: [PATCH] Add cleaning network docs

Ironic requires a cleaning network uuid in Kilo when using the default
config. This adds docs for how to configure the option and notes this
must be done when upgrading from Juno to Kilo.

Change-Id: Ia5cc118daefa7e3d966f1ff219ab024cb47d81f5
---
 doc/source/deploy/cleaning.rst      |  6 ++++++
 doc/source/deploy/install-guide.rst | 31 +++++++++++++++++++++++++++++
 doc/source/deploy/upgrade-guide.rst | 13 ++++++++++++
 3 files changed, 50 insertions(+)

diff --git a/doc/source/deploy/cleaning.rst b/doc/source/deploy/cleaning.rst
index 0f1a42edac..0f552dd9b4 100644
--- a/doc/source/deploy/cleaning.rst
+++ b/doc/source/deploy/cleaning.rst
@@ -34,6 +34,12 @@ This will enable the default set of steps, based on your hardware and Ironic
 drivers. If you're using an agent_* driver, this includes, by default, erasing
 all of the previous tenant's data.
 
+If you are using the Neutron DHCP provider (the default) you will also need to
+ensure you have configured a cleaning network. This network will be used to
+boot the ramdisk for in-band cleaning. You can use the same network as your
+tenant network. For steps to set up the cleaning network, please see
+:ref:`CleaningNetworkSetup`.
+
 .. _InbandvsOutOfBandCleaning:
 
 In-Band vs Out-of-Band
diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst
index d30efc5a6e..0ba196cfa2 100644
--- a/doc/source/deploy/install-guide.rst
+++ b/doc/source/deploy/install-guide.rst
@@ -462,6 +462,37 @@ DHCP and PXE Boot configuration. An example of this is shown in the
     --ip-version=4 --gateway=$GATEWAY_IP --allocation-pool \
     start=$START_IP,end=$END_IP --enable-dhcp
 
+.. _CleaningNetworkSetup:
+
+Configure the Bare Metal Service for Cleaning
+=============================================
+
+#. If you configure Ironic to use :ref:`cleaning` (which is enabled by
+   default), you will need to set the ``cleaning_network_uuid`` configuration
+   option. Note the network UUID (the `id` field) of the network you created in
+   :ref:`NeutronFlatNetworking` or another network you created for cleaning::
+
+    neutron net-list
+
+#. Configure the cleaning network UUID via the ``cleaning_network_uuid``
+   option in the Ironic configuration file (/etc/ironic/ironic.conf). In the
+   following, replace NETWORK_UUID with the UUID you noted in the previous
+   step::
+
+    [neutron]
+    ...
+
+    # UUID of the network to create Neutron ports on when booting
+    # to a ramdisk for cleaning/zapping using Neutron DHCP (string
+    # value)
+    #cleaning_network_uuid=<None>
+    cleaning_network_uuid = NETWORK_UUID
+
+#. Restart the Bare Metal Service::
+
+    service ironic-api restart
+    service ironic-conductor restart
+
 Image Requirements
 ==================
 
diff --git a/doc/source/deploy/upgrade-guide.rst b/doc/source/deploy/upgrade-guide.rst
index 2ce9e09526..e2001a5c84 100644
--- a/doc/source/deploy/upgrade-guide.rst
+++ b/doc/source/deploy/upgrade-guide.rst
@@ -34,3 +34,16 @@ Note that during the period between Nova's upgrade and Ironic's upgrades,
 instances can still be provisioned to nodes, however, any attempt by users
 to specify a config drive for an instance will cause error until Ironic's
 upgrade has completed.
+
+Cleaning
+--------
+A new feature in Kilo is support for the cleaning of nodes between workloads to
+ensure the node is ready for another workload. This can include erasing the
+hard drives, updating firmware, and other steps. For more information, see
+:ref:`cleaning`.
+
+If Ironic is configured with cleaning enabled (defaults to True) and to use
+Neutron as the DHCP provider (also the default), you will need to set the
+`cleaning_network_uuid` option in the Ironic configuration file before starting
+the Kilo Ironic service. See :ref:`CleaningNetworkSetup` for information on
+how to set up the cleaning network for Ironic.