From 5869f9b17f37c0d5dd8e797da55cb749e906d5b1 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Wed, 13 Dec 2017 12:59:42 +0000
Subject: [PATCH] Add more detail on baremetal compute state transitions

---
 doc/source/administration.rst | 42 +++++++++++++++++++++++++----------
 1 file changed, 30 insertions(+), 12 deletions(-)

diff --git a/doc/source/administration.rst b/doc/source/administration.rst
index 51ad20d27..461931406 100644
--- a/doc/source/administration.rst
+++ b/doc/source/administration.rst
@@ -135,22 +135,40 @@ In all cases, commands are delegated to one of the controller hosts, and
 executed concurrently. Note that ansible's ``forks`` configuration option,
 which defaults to 5, may limit the number of nodes configured concurrently.
 
-To move the baremetal compute nodes to the ``manageable`` provision state::
-
-    (kayobe) $ kayobe baremetal compute manage
-
-To move the baremetal compute nodes to the ``available`` provision state::
-
-    (kayobe) $ kayobe baremetal compute provide
-
-To trigger hardware inspection on the baremetal compute nodes::
-
-    (kayobe) $ kayobe baremetal compute inspect
-
 By default these commands wait for the state transition to complete for each
 node. This behavior can be changed by overriding the variable
 ``baremetal_compute_wait`` via ``-e baremetal_compute_wait=False``
 
+Manage
+------
+
+A node may need to be set to the ``manageable`` provision state in order to
+perform certain management operations, or when an enrolled node is
+transitioned into service. In order to manage a node, it must be in one of
+these states: ``enroll``, ``available``, ``cleaning``, ``clean failed``,
+``adopt failed`` or ``inspect failed``. To move the baremetal compute nodes
+to the ``manageable`` provision state::
+
+    (kayobe) $ kayobe baremetal compute manage
+
+Provide
+-------
+
+In order for nodes to be scheduled by nova, they must be ``available``. To
+move the baremetal compute nodes from the ``manageable`` state to the
+``available`` provision state::
+
+    (kayobe) $ kayobe baremetal compute provide
+
+Inspect
+-------
+
+Nodes must be in one of the following states: ``manageable``, ``inspect
+failed``, or ``available``. To trigger hardware inspection on the baremetal
+compute nodes::
+
+    (kayobe) $ kayobe baremetal compute inspect
+
 Running Kayobe Playbooks on Demand
 ==================================