Rework nodes registration and configuration

* Convert some notes to warnings, move important text out of notes.
* Move enroll state documentation into a newly written section
  (mostly copy-pasted from one of my recent emails to openstack-dev).
* Stop mentioning API version 1.11, as we already use it by default.
* Explain the 'baremetal configure boot' is no longer mandatory
  starting with Newton.
* Write a section on automatically setting the root device hints.
* Move power state sync note to troubleshooting, as people are unlikely
  to be interested in or even understand this part.
* Fix small mistakes.

Change-Id: I5f078bafd64d4fbcc5e83557f7761226cca93fd6

doc/source/advanced_deployment/advanced_deployment.rst

@@ -6,6 +6,7 @@ In this chapter you will find advanced deployment of various |project| areas.
 
 .. toctree::
 
+   node_states
    root_device
    build_single_image
    introspect_single_node

doc/source/advanced_deployment/introspect_single_node.rst

@@ -5,7 +5,8 @@ In addition to bulk introspection, you can also introspect nodes one by one.
 When doing so, you must take care to set the correct node states manually.
 Use ``ironic node-show UUID`` command to figure out whether nodes are in
 ``manageable`` or ``available`` state. For all nodes in ``available`` state,
-start with putting a node to ``manageable`` state::
+start with putting a node to ``manageable`` state (see
+:doc:`../advanced_deployment/node_states` for details)::
 
     ironic node-set-provision-state UUID manage
 

doc/source/advanced_deployment/node_states.rst

@@ -0,0 +1,58 @@
+Bare Metal Node States
+======================
+
+This document provides a brief explanation of the bare metal node states that
+TripleO uses or might use. Please refer to `the Ironic documentation
+<http://docs.openstack.org/developer/ironic/>`_ for more details.
+
+enroll
+------
+
+With recent versions of the bare metal API (starting with 1.11), nodes begin
+their life in a state called ``enroll``. Nodes in this state are not available
+for deployment, nor for most of other actions. Ironic does not touch such nodes
+in any way.
+
+Starting with the Newton release, TripleO node registration command allows
+to import nodes in this state instead of the default ``available``.
+To do so pass the option ``--initial-state=enroll``::
+
+    openstack baremetal import --initial-state=enroll instackenv.json
+
+Then move the nodes to manageable_ state and eventually to available_.
+
+manageable
+----------
+
+To make nodes alive an operator uses ``manage`` provisioning action to move
+nodes to ``manageable`` state. During this transition the power and management
+credentials (IPMI, SSH, etc) are validated to ensure that nodes in
+``manageable`` state are actually manageable by Ironic. This state is still not
+available for deployment.  With nodes in this state an operator can execute
+various pre-deployment actions, such as introspection, RAID configuration, etc.
+So to sum it up, nodes in ``manageable`` state are being configured before
+exposing them into the cloud.
+
+Nodes get into ``manageable`` state automatically. The ``manage`` action
+can be used to bring nodes already moved to available_ state back to
+``manageable`` for configuration::
+
+    ironic node-set-provision-state <NAME OR UUID> manage
+
+
+available
+---------
+
+The last step before the deployment is to make nodes ``available`` using the
+``provide`` provisioning action. Such nodes are exposed to nova, and can be
+deployed to at any moment. No long-running configuration actions should be run
+in this state.
+
+.. note::
+   The TripleO introspection command ``openstack baremetal introspection bulk
+   start`` moves ``available`` nodes to manageable_ state automatically
+   before and moves them back after a successful introspection. However, nodes
+   which failed introspection stay in ``manageable`` state and must be
+   reintrospected or made ``available`` manually::
+
+    ironic node-set-provision-state <NAME OR UUID> provide

doc/source/advanced_deployment/root_device.rst

@@ -27,6 +27,32 @@ Where the new value is calculated as a real disk size in GiB minus 1 GiB to
 account for partitioning (the introspection process does this calculation
 automatically).
 
+Setting root device hints automatically
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting with the Newton release it is possible to autogenerate root device
+hints for all nodes instead of setting them one by one. Pass the
+``--root-device`` argument to the ``openstack baremetal configure boot``
+**after a successful introspection**. This argument can accept a device list
+in the order of preference, for example::
+
+    openstack baremetal configure boot --root-device=sdb,sdc,vda
+
+It can also accept one of two strategies: ``smallest`` will pick the smallest
+device, ``largest`` will pick the largest one. By default only disk devices
+larger than 4 GiB are considered at all, set the ``--root-device-minimum-size``
+argument to change.
+
+.. note::
+   Subsequent runs of this command on the same set of nodes does nothing,
+   as root device hints are already recorded on nodes and are not overwritten.
+   If you want to change existing root device hints, first remove them manually
+   as described above.
+
+.. note::
+   This command relies on introspection data, so if you change disk devices on
+   the machines, introspection must be rerun before rerunning this command.
+
 Using introspection data to find the root device
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/basic_deployment/basic_deployment_cli.rst

@@ -175,24 +175,42 @@ Load the images into the undercloud Glance::
 Register Nodes
 --------------
 
-Register nodes for your deployment with Ironic::
+Register and configure nodes for your deployment with Ironic::
 
     openstack baremetal import instackenv.json
 
-.. note::
+The file to be imported may be either JSON, YAML or CSV format, and
-   The file to be imported may be either JSON, YAML or CSV format, and
+the type is detected via the file extension (json, yaml, csv).
-   the type is detected via the file extension (json, yaml, csv).
+The file format is documented in :ref:`instackenv`.
 
 .. admonition:: Stable Branch
    :class: stable
 
-   If you're running an old (stable/liberty or older) tripleoclient version
+   For TripleO release Liberty and older an explicit ``--json`` or ``--csv``
-   however then you must specify --json explicitly and only use that format.
+   flag is required for JSON and CSV formats accordingly.
 
-.. note::
+.. admonition:: Stable Branch
-   The file format for node import is documented, see :ref:`instackenv`.
+   :class: stable
 
-.. note::
+   For TripleO release Mitaka and older the following command must be run
+   after registration to assign the deployment kernel and ramdisk to all nodes:
+
+        openstack baremetal configure boot
+
+Starting with the Newton release you can take advantage of the ``enroll``
+provisioning state - see :doc:`../advanced_deployment/node_states` for details.
+
+If your hardware has several hard drives, it's highly recommended that you
+specify the exact device to be used during introspection and deployment
+as a root device. Please see :ref:`root_device` for details.
+
+.. warning::
+   If you don't specify the root device explicitly, any device may be picked.
+   Also the device chosen automatically is **NOT** guaranteed to be the same
+   across rebuilds. Make sure to wipe the previous installation before
+   rebuilding in this case.
+
+.. warning::
    It's not recommended to delete nodes and/or rerun this command after
    you have proceeded to the next steps. Particularly, if you start introspection
    and then re-register nodes, you won't be able to retry introspection until
@@ -200,41 +218,6 @@ Register nodes for your deployment with Ironic::
    with nodes after registration, please follow
    :ref:`node_registration_problems`.
 
-.. note::
-   By default Ironic will not sync the power state of the nodes,
-   because in our HA (high availability) model Pacemaker is the
-   one responsible for controlling the power state of the nodes
-   when fencing.  If you are using a non-HA setup and want Ironic
-   to take care of the power state of the nodes please change the
-   value of the "force_power_state_during_sync" configuration option
-   in the /etc/ironic/ironic.conf file to "True" and restart the
-   openstack-ironic-conductor service.
-
-   Also, note that if ``openstack undercloud install`` is re-run the value of
-   the "force_power_state_during_sync" configuration option will be set back to
-   the default, which is "False".
-
-.. note::
-   If you want to take advantage of the ENROLL provisioning state introduced in
-   OpenStack Liberty, you must enable an Ironic API version >= 1.11 (for
-   instance by setting the OS_BAREMETAL_API_VERSION environment variable), and
-   pass the option ``--initial-state=enroll`` to ``openstack baremetal
-   import``.
-
-Assign kernel and ramdisk to nodes::
-
-    openstack baremetal configure boot
-
-.. note::
-    If your hardware has several hard drives, it's highly recommended that you
-    specify the exact device to be used during introspection and deployment
-    as a root device. Please see :ref:`root_device` for details.
-
-    If you don't specify the root device explicitly, any device may be picked.
-    Also the device chosen automatically is NOT guaranteed to be the same
-    across rebuilds. Make sure to wipe the previous installation before
-    rebuilding in this case.
-
 .. _introspection:
 
 Introspect Nodes

doc/source/troubleshooting/troubleshooting-nodes.rst

@@ -42,6 +42,22 @@ A Wrong IPMI address can be fixed with the following command::
 
     ironic node-update <NODE UUID> replace driver_info/ipmi_address=<NEW IPMI ADDRESS>
 
+Node power state is not enforced by Ironic
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default Ironic will not forcibly sync the power state of the nodes,
+because in our HA (high availability) model Pacemaker is the
+one responsible for controlling the power state of the nodes
+when fencing.  If you are using a non-HA setup and want Ironic
+to take care of the power state of the nodes please change the
+value of the ``force_power_state_during_sync`` configuration option
+in the ``/etc/ironic/ironic.conf`` file to ``True`` and restart the
+openstack-ironic-conductor service.
+
+Also, note that if ``openstack undercloud install`` is re-run the value of
+the ``force_power_state_during_sync`` configuration option will be set back to
+the default, which is ``False``.
+
 
 .. _introspection_problems: