[install-guide] Import "Enrollment" and "Troubleshooting" sections

Change-Id: Ie8b570d2a54c38a9d04976a0430fe0d963db57b0
Partial-bug: #1612278
(cherry picked from commit 0445213bbbaca44346e4d1160134ae1ac57bd049)

6 files changed, 535 insertions, 523 deletions

diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst
index 0e955069d..5a2f5ba13 100644
--- a/doc/source/deploy/install-guide.rst
+++ b/doc/source/deploy/install-guide.rst
@@ -622,397 +622,10 @@ Metal service Install Guide.
 Enrollment
 ==========
 
-After all the services have been properly configured, you should enroll your
-hardware with the Bare Metal service, and confirm that the Compute service sees
-the available hardware. The nodes will be visible to the Compute service once
-they are in the ``available`` provision state.
-
-.. note::
-   After enrolling nodes with the Bare Metal service, the Compute service
-   will not be immediately notified of the new resources. The Compute service's
-   resource tracker syncs periodically, and so any changes made directly to the
-   Bare Metal service's resources will become visible in the Compute service
-   only after the next run of that periodic task.
-   More information is in the `Troubleshooting`_ section below.
-
-.. note::
-   Any bare metal node that is visible to the Compute service may have a
-   workload scheduled to it, if both the ``power`` and ``deploy`` interfaces
-   pass the ``validate`` check.
-   If you wish to exclude a node from the Compute service's scheduler, for
-   instance so that you can perform maintenance on it, you can set the node to
-   "maintenance" mode.
-   For more information see the `Maintenance Mode`_ section below.
-
-Enrollment process
-------------------
-
-This section describes the main steps to enroll a node and make it available
-for provisioning. Some steps are shown separately for illustration purposes,
-and may be combined if desired.
-
-#. Create a node in the Bare Metal service. At a minimum, you must
-   specify the driver name (for example, "pxe_ipmitool").
-   This will return the node UUID along with other information
-   about the node. The node's provision state will be ``available``. (The
-   example assumes that the client is using the default API version.)::
-
-    ironic node-create -d pxe_ipmitool
-    +--------------+--------------------------------------+
-    | Property     | Value                                |
-    +--------------+--------------------------------------+
-    | uuid         | dfc6189f-ad83-4261-9bda-b27258eb1987 |
-    | driver_info  | {}                                   |
-    | extra        | {}                                   |
-    | driver       | pxe_ipmitool                         |
-    | chassis_uuid |                                      |
-    | properties   | {}                                   |
-    | name         | None                                 |
-    +--------------+--------------------------------------+
-
-    ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987
-    +------------------------+--------------------------------------+
-    | Property               | Value                                |
-    +------------------------+--------------------------------------+
-    | target_power_state     | None                                 |
-    | extra                  | {}                                   |
-    | last_error             | None                                 |
-    | maintenance_reason     | None                                 |
-    | provision_state        | available                            |
-    | uuid                   | dfc6189f-ad83-4261-9bda-b27258eb1987 |
-    | console_enabled        | False                                |
-    | target_provision_state | None                                 |
-    | provision_updated_at   | None                                 |
-    | maintenance            | False                                |
-    | power_state            | None                                 |
-    | driver                 | pxe_ipmitool                         |
-    | properties             | {}                                   |
-    | instance_uuid          | None                                 |
-    | name                   | None                                 |
-    | driver_info            | {}                                   |
-    | ...                    | ...                                  |
-    +------------------------+--------------------------------------+
-
-   Beginning with the Kilo release a node may also be referred to by a logical
-   name as well as its UUID. To utilize this new feature a name must be
-   assigned to the node. This can be done when the node is created by
-   adding the ``-n`` option to the ``node-create`` command or by updating an
-   existing node with the ``node-update`` command. See `Logical Names`_ for
-   examples.
-
-   Beginning with the Liberty release, with API version 1.11 and above, a newly
-   created node will have an initial provision state of ``enroll`` as opposed to
-   ``available``. See `Enrolling a node`_ for more details.
-
-#. Update the node ``driver_info`` so that Bare Metal service can manage the
-   node. Different drivers may require different information about the node.
-   You can determine this with the ``driver-properties`` command, as follows::
-
-    ironic driver-properties pxe_ipmitool
-    +----------------------+-------------------------------------------------------------------------------------------------------------+
-    | Property             | Description                                                                                                 |
-    +----------------------+-------------------------------------------------------------------------------------------------------------+
-    | ipmi_address         | IP address or hostname of the node. Required.                                                               |
-    | ipmi_password        | password. Optional.                                                                                         |
-    | ipmi_username        | username; default is NULL user. Optional.                                                                   |
-    | ...                  | ...                                                                                                         |
-    | deploy_kernel        | UUID (from Glance) of the deployment kernel. Required.                                                      |
-    | deploy_ramdisk       | UUID (from Glance) of the ramdisk that is mounted at boot time. Required.                                   |
-    +----------------------+-------------------------------------------------------------------------------------------------------------+
-
-    ironic node-update $NODE_UUID add \
-    driver_info/ipmi_username=$USER \
-    driver_info/ipmi_password=$PASS \
-    driver_info/ipmi_address=$ADDRESS
-
-   .. note::
-      If IPMI is running on a port other than 623 (the default). The port must
-      be added to ``driver_info`` by specifying the ``ipmi_port`` value.
-      Example::
-
-       ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER
-
-      Note that you may also specify all ``driver_info`` parameters during
-      ``node-create`` by passing the **-i** option multiple times.
-
-#. Update the node's properties to match the bare metal flavor you created
-   earlier::
-
-    ironic node-update $NODE_UUID add \
-    properties/cpus=$CPU \
-    properties/memory_mb=$RAM_MB \
-    properties/local_gb=$DISK_GB \
-    properties/cpu_arch=$ARCH
-
-   As above, these can also be specified at node creation by passing the **-p**
-   option to ``node-create`` multiple times.
-
-#. If you wish to perform more advanced scheduling of the instances based on
-   hardware capabilities, you may add metadata to each node that will be
-   exposed to the nova scheduler (see: `ComputeCapabilitiesFilter`_).  A full
-   explanation of this is outside of the scope of this document. It can be done
-   through the special ``capabilities`` member of node properties::
-
-    ironic node-update $NODE_UUID add \
-    properties/capabilities=key1:val1,key2:val2
-
-#. As mentioned in the `Flavor Creation`_ section, if using the Kilo or later
-   release of Bare Metal service, you should specify a deploy kernel and
-   ramdisk which correspond to the node's driver, for example::
-
-    ironic node-update $NODE_UUID add \
-    driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
-    driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
-
-#. You must also inform Bare Metal service of the network interface cards which
-   are part of the node by creating a port with each NIC's MAC address.
-   These MAC addresses are passed to the Networking service during instance
-   provisioning and used to configure the network appropriately::
-
-    ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
-
-#. To check if Bare Metal service has the minimum information necessary for
-   a node's driver to function, you may ``validate`` it::
-
-    ironic node-validate $NODE_UUID
-
-    +------------+--------+--------+
-    | Interface  | Result | Reason |
-    +------------+--------+--------+
-    | console    | True   |        |
-    | deploy     | True   |        |
-    | management | True   |        |
-    | power      | True   |        |
-    +------------+--------+--------+
-
-   If the node fails validation, each driver will return information as to why
-   it failed::
-
-    ironic node-validate $NODE_UUID
-
-    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
-    | Interface  | Result | Reason                                                                                                                              |
-    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
-    | console    | None   | not supported                                                                                                                       |
-    | deploy     | False  | Cannot validate iSCSI deploy. Some parameters were missing in node's instance_info. Missing are: ['root_gb', 'image_source']        |
-    | management | False  | Missing the following IPMI credentials in node's driver_info: ['ipmi_address'].                                                     |
-    | power      | False  | Missing the following IPMI credentials in node's driver_info: ['ipmi_address'].                                                     |
-    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
-
-#. If using API version 1.11 or above, the node was created in the ``enroll``
-   provision state. In order for the node to be available for deploying a
-   workload (for example, by the Compute service), it needs to be in the
-   ``available`` provision state. To do this, it must be moved into the
-   ``manageable`` state and then moved into the ``available`` state. The
-   `API version 1.11 and above`_ section describes the commands for this.
-
-.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter
-
-
-Enrolling a node
-----------------
-In the Liberty cycle, starting with API version 1.11, the Bare Metal service
-added a new initial provision state of ``enroll`` to its state machine.
-
-Existing automation tooling that use an API version lower than 1.11 are not
-affected, since the initial provision state is still ``available``.
-However, using API version 1.11 or above may break existing automation tooling
-with respect to node creation.
-
-The default API version used by (the most recent) python-ironicclient is 1.9.
-
-The examples below set the API version for each command. To set the
-API version for all commands, you can set the environment variable
-``IRONIC_API_VERSION``.
-
-API version 1.10 and below
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Below is an example of creating a node with API version 1.10. After creation,
-the node will be in the ``available`` provision state.
-Other API versions below 1.10 may be substituted in place of 1.10.
-
-::
-
-    ironic --ironic-api-version 1.10 node-create -d agent_ilo -n pre11
-
-    +--------------+--------------------------------------+
-    | Property     | Value                                |
-    +--------------+--------------------------------------+
-    | uuid         | cc4998a0-f726-4927-9473-0582458c6789 |
-    | driver_info  | {}                                   |
-    | extra        | {}                                   |
-    | driver       | agent_ilo                            |
-    | chassis_uuid |                                      |
-    | properties   | {}                                   |
-    | name         | pre11                                |
-    +--------------+--------------------------------------+
-
-
-    ironic --ironic-api-version 1.10 node-list
-
-    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
-    | UUID                                 | Name  | Instance UUID | Power State | Provisioning State | Maintenance |
-    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
-    | cc4998a0-f726-4927-9473-0582458c6789 | pre11 | None          | None        | available          | False       |
-    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
-
-API version 1.11 and above
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Beginning with API version 1.11, the initial provision state for newly created
-nodes is ``enroll``. In the examples below, other API versions above 1.11 may be
-substituted in place of 1.11.
-::
-
-    ironic --ironic-api-version 1.11 node-create -d agent_ilo -n post11
-
-    +--------------+--------------------------------------+
-    | Property     | Value                                |
-    +--------------+--------------------------------------+
-    | uuid         | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 |
-    | driver_info  | {}                                   |
-    | extra        | {}                                   |
-    | driver       | agent_ilo                            |
-    | chassis_uuid |                                      |
-    | properties   | {}                                   |
-    | name         | post11                               |
-    +--------------+--------------------------------------+
-
-
-    ironic --ironic-api-version 1.11 node-list
-
-    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
-    | UUID                                 | Name   | Instance UUID | Power State | Provisioning State | Maintenance |
-    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
-    | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | post11 | None          | None        | enroll             | False       |
-    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
-
-In order for nodes to be available for deploying workloads on them, nodes
-must be in the ``available`` provision state. To do this, nodes
-created with API version 1.11 and above must be moved from the ``enroll`` state
-to the ``manageable`` state and then to the ``available`` state.
-
-To move a node to a different provision state, use the
-``node-set-provision-state`` command.
-
-.. note:: Since it is an asychronous call, the response for
-          ``ironic node-set-provision-state`` will not indicate whether the
-          transition succeeded or not. You can check the status of the
-          operation via ``ironic node-show``. If it was successful,
-          ``provision_state`` will be in the desired state. If it failed,
-          there will be information in the node's ``last_error``.
-
-After creating a node and before moving it from its initial provision state of
-``enroll``, basic power and port information needs to be configured on the node.
-The Bare Metal service needs this information because it verifies that it is
-capable of controlling the node when transitioning the node from ``enroll`` to
-``manageable`` state.
-
-To move a node from ``enroll`` to ``manageable`` provision state::
-
-    ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage
-
-    ironic node-show $NODE_UUID
-
-    +------------------------+--------------------------------------------------------------------+
-    | Property               | Value                                                              |
-    +------------------------+--------------------------------------------------------------------+
-    | ...                    | ...                                                                |
-    | provision_state        | manageable                                                         | <- verify correct state
-    | uuid                   | 0eb013bb-1e4b-4f4c-94b5-2e7468242611                               |
-    | ...                    | ...                                                                |
-    +------------------------+--------------------------------------------------------------------+
-
-When a node is moved from the ``manageable`` to ``available`` provision
-state, the node will go through automated cleaning if configured to do so (see
-:ref:`CleaningNetworkSetup`).
-To move a node from ``manageable`` to ``available`` provision state::
-
-    ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID provide
-
-    ironic node-show $NODE_UUID
-
-    +------------------------+--------------------------------------------------------------------+
-    | Property               | Value                                                              |
-    +------------------------+--------------------------------------------------------------------+
-    | ...                    | ...                                                                |
-    | provision_state        | available                                                          | < - verify correct state
-    | uuid                   | 0eb013bb-1e4b-4f4c-94b5-2e7468242611                               |
-    | ...                    | ...                                                                |
-    +------------------------+--------------------------------------------------------------------+
-
-
-For more details on the Bare Metal service's state machine, see the
-`state machine <http://docs.openstack.org/developer/ironic/dev/states.html>`_
-documentation.
-
-
-Logical names
--------------
-Beginning with the Kilo release a Node may also be referred to by a
-logical name as well as its UUID. Names can be assigned either when
-creating the node by adding the ``-n`` option to the ``node-create`` command or
-by updating an existing node with the ``node-update`` command.
-
-Node names must be unique, and conform to:
-
-- rfc952_
-- rfc1123_
-- wiki_hostname_
-
-The node is named 'example' in the following examples:
-::
-
-    ironic node-create -d agent_ipmitool -n example
-
-or::
-
-    ironic node-update $NODE_UUID add name=example
-
-
-Once assigned a logical name, a node can then be referred to by name or
-UUID interchangeably.
-::
-
-    ironic node-create -d agent_ipmitool -n example
-
-    +--------------+--------------------------------------+
-    | Property     | Value                                |
-    +--------------+--------------------------------------+
-    | uuid         | 71e01002-8662-434d-aafd-f068f69bb85e |
-    | driver_info  | {}                                   |
-    | extra        | {}                                   |
-    | driver       | agent_ipmitool                       |
-    | chassis_uuid |                                      |
-    | properties   | {}                                   |
-    | name         | example                              |
-    +--------------+--------------------------------------+
-
-
-    ironic node-show example
-
-    +------------------------+--------------------------------------+
-    | Property               | Value                                |
-    +------------------------+--------------------------------------+
-    | target_power_state     | None                                 |
-    | extra                  | {}                                   |
-    | last_error             | None                                 |
-    | updated_at             | 2015-04-24T16:23:46+00:00            |
-    | ...                    | ...                                  |
-    | instance_info          | {}                                   |
-    +------------------------+--------------------------------------+
-
-.. _rfc952: http://tools.ietf.org/html/rfc952
-.. _rfc1123: http://tools.ietf.org/html/rfc1123
-.. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname
-
-
-Hardware Inspection
--------------------
+The `Enrollment`_ section has been moved to the Bare Metal service Install
+Guide.
 
-Starting with the Kilo release, Bare Metal service supports hardware inspection
-that simplifies enrolling nodes - please see :ref:`inspection` for details.
+.. _`Enrollment`: http://docs.openstack.org/project-install-guide/baremetal/draft/enrollment.html
 
 Specifying the disk for deployment
 ==================================
@@ -1515,6 +1128,8 @@ the `CoreOS tools`_ at:
 * `CoreOS deploy kernel <http://tarballs.openstack.org/ironic-python-agent/coreos/files/coreos_production_pxe.vmlinuz>`_
 * `CoreOS deploy ramdisk <http://tarballs.openstack.org/ironic-python-agent/coreos/files/coreos_production_pxe_image-oem.cpio.gz>`_
 
+.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/
+
 Building from source
 --------------------
 
@@ -1673,123 +1288,7 @@ with PXE and Nova:
 Troubleshooting
 ===============
 
-Once all the services are running and configured properly, and a node has been
-enrolled with the Bare Metal service and is in the ``available`` provision
-state, the Compute service should detect the node
-as an available resource and expose it to the scheduler.
-
-.. note::
-   There is a delay, and it may take up to a minute (one periodic task cycle)
-   for the Compute service to recognize any changes in the Bare Metal service's
-   resources (both additions and deletions).
-
-In addition to watching ``nova-compute`` log files, you can see the available
-resources by looking at the list of Compute hypervisors. The resources reported
-therein should match the bare metal node properties, and the Compute service flavor.
-
-Here is an example set of commands to compare the resources in Compute
-service and Bare Metal service::
-
-    $ ironic node-list
-    +--------------------------------------+---------------+-------------+--------------------+-------------+
-    | UUID                                 | Instance UUID | Power State | Provisioning State | Maintenance |
-    +--------------------------------------+---------------+-------------+--------------------+-------------+
-    | 86a2b1bb-8b29-4964-a817-f90031debddb | None          | power off   | available          | False       |
-    +--------------------------------------+---------------+-------------+--------------------+-------------+
-
-    $ ironic node-show 86a2b1bb-8b29-4964-a817-f90031debddb
-    +------------------------+----------------------------------------------------------------------+
-    | Property               | Value                                                                |
-    +------------------------+----------------------------------------------------------------------+
-    | instance_uuid          | None                                                                 |
-    | properties             | {u'memory_mb': u'1024', u'cpu_arch': u'x86_64', u'local_gb': u'10',  |
-    |                        | u'cpus': u'1'}                                                       |
-    | maintenance            | False                                                                |
-    | driver_info            | { [SNIP] }                                                           |
-    | extra                  | {}                                                                   |
-    | last_error             | None                                                                 |
-    | created_at             | 2014-11-20T23:57:03+00:00                                            |
-    | target_provision_state | None                                                                 |
-    | driver                 | pxe_ipmitool                                                         |
-    | updated_at             | 2014-11-21T00:47:34+00:00                                            |
-    | instance_info          | {}                                                                   |
-    | chassis_uuid           | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59                                 |
-    | provision_state        | available                                                            |
-    | reservation            | None                                                                 |
-    | power_state            | power off                                                            |
-    | console_enabled        | False                                                                |
-    | uuid                   | 86a2b1bb-8b29-4964-a817-f90031debddb                                 |
-    +------------------------+----------------------------------------------------------------------+
-
-    $ nova hypervisor-show 1
-    +-------------------------+--------------------------------------+
-    | Property                | Value                                |
-    +-------------------------+--------------------------------------+
-    | cpu_info                | baremetal cpu                        |
-    | current_workload        | 0                                    |
-    | disk_available_least    | -                                    |
-    | free_disk_gb            | 10                                   |
-    | free_ram_mb             | 1024                                 |
-    | host_ip                 | [ SNIP ]                             |
-    | hypervisor_hostname     | 86a2b1bb-8b29-4964-a817-f90031debddb |
-    | hypervisor_type         | ironic                               |
-    | hypervisor_version      | 1                                    |
-    | id                      | 1                                    |
-    | local_gb                | 10                                   |
-    | local_gb_used           | 0                                    |
-    | memory_mb               | 1024                                 |
-    | memory_mb_used          | 0                                    |
-    | running_vms             | 0                                    |
-    | service_disabled_reason | -                                    |
-    | service_host            | my-test-host                         |
-    | service_id              | 6                                    |
-    | state                   | up                                   |
-    | status                  | enabled                              |
-    | vcpus                   | 1                                    |
-    | vcpus_used              | 0                                    |
-    +-------------------------+--------------------------------------+
-
-
-Maintenance mode
-----------------
-Maintenance mode may be used if you need to take a node out of the resource
-pool. Putting a node in maintenance mode will prevent Bare Metal service from
-executing periodic tasks associated with the node. This will also prevent
-Compute service from placing a tenant instance on the node by not exposing
-the node to the nova scheduler. Nodes can be placed into maintenance mode
-with the following command.
-::
-
-    $ ironic node-set-maintenance $NODE_UUID on
-
-As of the Kilo release, a maintenance reason may be included with the optional
-``--reason`` command line option. This is a free form text field that will be
-displayed in the ``maintenance_reason`` section of the ``node-show`` command.
-::
-
-    $ ironic node-set-maintenance $UUID on --reason "Need to add ram."
-
-    $ ironic node-show $UUID
-
-    +------------------------+--------------------------------------+
-    | Property               | Value                                |
-    +------------------------+--------------------------------------+
-    | target_power_state     | None                                 |
-    | extra                  | {}                                   |
-    | last_error             | None                                 |
-    | updated_at             | 2015-04-27T15:43:58+00:00            |
-    | maintenance_reason     | Need to add ram.                     |
-    | ...                    | ...                                  |
-    | maintenance            | True                                 |
-    | ...                    | ...                                  |
-    +------------------------+--------------------------------------+
-
-To remove maintenance mode and clear any ``maintenance_reason`` use the
-following command.
-::
-
-    $ ironic node-set-maintenance $NODE_UUID off
-
+The `Troubleshooting`_ section has been moved to the Bare Metal service Install
+Guide.
 
-.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/
-.. _diskimage-builder: http://docs.openstack.org/developer/diskimage-builder/
+.. _`Troubleshooting`: http://docs.openstack.org/project-install-guide/baremetal/draft/troubleshooting.html
diff --git a/install-guide/source/enrollment.rst b/install-guide/source/enrollment.rst
new file mode 100644
index 000000000..49ff012d3
--- /dev/null
+++ b/install-guide/source/enrollment.rst
@@ -0,0 +1,398 @@
+.. _enrollment:
+
+Enrollment
+==========
+
+After all the services have been properly configured, you should enroll your
+hardware with the Bare Metal service, and confirm that the Compute service sees
+the available hardware. The nodes will be visible to the Compute service once
+they are in the ``available`` provision state.
+
+.. note::
+   After enrolling nodes with the Bare Metal service, the Compute service
+   will not be immediately notified of the new resources. The Compute service's
+   resource tracker syncs periodically, and so any changes made directly to the
+   Bare Metal service's resources will become visible in the Compute service
+   only after the next run of that periodic task.
+   More information is in the :ref:`troubleshooting` section.
+
+.. note::
+   Any bare metal node that is visible to the Compute service may have a
+   workload scheduled to it, if both the ``power`` and ``deploy`` interfaces
+   pass the ``validate`` check.
+   If you wish to exclude a node from the Compute service's scheduler, for
+   instance so that you can perform maintenance on it, you can set the node to
+   "maintenance" mode.
+   For more information see the :ref:`maintenance_mode` section.
+
+Enrollment process
+------------------
+
+This section describes the main steps to enroll a node and make it available
+for provisioning. Some steps are shown separately for illustration purposes,
+and may be combined if desired.
+
+#. Create a node in the Bare Metal service. At a minimum, you must
+   specify the driver name (for example, "pxe_ipmitool").
+   This will return the node UUID along with other information
+   about the node. The node's provision state will be ``available``. (The
+   example assumes that the client is using the default API version.)::
+
+    ironic node-create -d pxe_ipmitool
+    +--------------+--------------------------------------+
+    | Property     | Value                                |
+    +--------------+--------------------------------------+
+    | uuid         | dfc6189f-ad83-4261-9bda-b27258eb1987 |
+    | driver_info  | {}                                   |
+    | extra        | {}                                   |
+    | driver       | pxe_ipmitool                         |
+    | chassis_uuid |                                      |
+    | properties   | {}                                   |
+    | name         | None                                 |
+    +--------------+--------------------------------------+
+
+    ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987
+    +------------------------+--------------------------------------+
+    | Property               | Value                                |
+    +------------------------+--------------------------------------+
+    | target_power_state     | None                                 |
+    | extra                  | {}                                   |
+    | last_error             | None                                 |
+    | maintenance_reason     | None                                 |
+    | provision_state        | available                            |
+    | uuid                   | dfc6189f-ad83-4261-9bda-b27258eb1987 |
+    | console_enabled        | False                                |
+    | target_provision_state | None                                 |
+    | provision_updated_at   | None                                 |
+    | maintenance            | False                                |
+    | power_state            | None                                 |
+    | driver                 | pxe_ipmitool                         |
+    | properties             | {}                                   |
+    | instance_uuid          | None                                 |
+    | name                   | None                                 |
+    | driver_info            | {}                                   |
+    | ...                    | ...                                  |
+    +------------------------+--------------------------------------+
+
+   Beginning with the Kilo release a node may also be referred to by a logical
+   name as well as its UUID. To utilize this new feature a name must be
+   assigned to the node. This can be done when the node is created by
+   adding the ``-n`` option to the ``node-create`` command or by updating an
+   existing node with the ``node-update`` command. See `Logical Names`_ for
+   examples.
+
+   Beginning with the Liberty release, with API version 1.11 and above, a newly
+   created node will have an initial provision state of ``enroll`` as opposed to
+   ``available``. See `Enrolling a node`_ for more details.
+
+#. Update the node ``driver_info`` so that Bare Metal service can manage the
+   node. Different drivers may require different information about the node.
+   You can determine this with the ``driver-properties`` command, as follows::
+
+    ironic driver-properties pxe_ipmitool
+    +----------------------+-------------------------------------------------------------------------------------------------------------+
+    | Property             | Description                                                                                                 |
+    +----------------------+-------------------------------------------------------------------------------------------------------------+
+    | ipmi_address         | IP address or hostname of the node. Required.                                                               |
+    | ipmi_password        | password. Optional.                                                                                         |
+    | ipmi_username        | username; default is NULL user. Optional.                                                                   |
+    | ...                  | ...                                                                                                         |
+    | deploy_kernel        | UUID (from Glance) of the deployment kernel. Required.                                                      |
+    | deploy_ramdisk       | UUID (from Glance) of the ramdisk that is mounted at boot time. Required.                                   |
+    +----------------------+-------------------------------------------------------------------------------------------------------------+
+
+    ironic node-update $NODE_UUID add \
+    driver_info/ipmi_username=$USER \
+    driver_info/ipmi_password=$PASS \
+    driver_info/ipmi_address=$ADDRESS
+
+   .. note::
+      If IPMI is running on a port other than 623 (the default). The port must
+      be added to ``driver_info`` by specifying the ``ipmi_port`` value.
+      Example::
+
+       ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER
+
+      Note that you may also specify all ``driver_info`` parameters during
+      ``node-create`` by passing the **-i** option multiple times.
+
+#. Update the node's properties to match the bare metal flavor you created
+   earlier::
+
+    ironic node-update $NODE_UUID add \
+    properties/cpus=$CPU \
+    properties/memory_mb=$RAM_MB \
+    properties/local_gb=$DISK_GB \
+    properties/cpu_arch=$ARCH
+
+   As above, these can also be specified at node creation by passing the **-p**
+   option to ``node-create`` multiple times.
+
+#. If you wish to perform more advanced scheduling of the instances based on
+   hardware capabilities, you may add metadata to each node that will be
+   exposed to the nova scheduler (see: `ComputeCapabilitiesFilter`_).  A full
+   explanation of this is outside of the scope of this document. It can be done
+   through the special ``capabilities`` member of node properties::
+
+    ironic node-update $NODE_UUID add \
+    properties/capabilities=key1:val1,key2:val2
+
+#. As mentioned in the :ref:`flavor-creation` section, if using the Kilo or later
+   release of Bare Metal service, you should specify a deploy kernel and
+   ramdisk which correspond to the node's driver, for example::
+
+    ironic node-update $NODE_UUID add \
+    driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
+    driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
+
+#. You must also inform Bare Metal service of the network interface cards which
+   are part of the node by creating a port with each NIC's MAC address.
+   These MAC addresses are passed to the Networking service during instance
+   provisioning and used to configure the network appropriately::
+
+    ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
+
+#. To check if Bare Metal service has the minimum information necessary for
+   a node's driver to function, you may ``validate`` it::
+
+    ironic node-validate $NODE_UUID
+
+    +------------+--------+--------+
+    | Interface  | Result | Reason |
+    +------------+--------+--------+
+    | console    | True   |        |
+    | deploy     | True   |        |
+    | management | True   |        |
+    | power      | True   |        |
+    +------------+--------+--------+
+
+   If the node fails validation, each driver will return information as to why
+   it failed::
+
+    ironic node-validate $NODE_UUID
+
+    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
+    | Interface  | Result | Reason                                                                                                                              |
+    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
+    | console    | None   | not supported                                                                                                                       |
+    | deploy     | False  | Cannot validate iSCSI deploy. Some parameters were missing in node's instance_info. Missing are: ['root_gb', 'image_source']        |
+    | management | False  | Missing the following IPMI credentials in node's driver_info: ['ipmi_address'].                                                     |
+    | power      | False  | Missing the following IPMI credentials in node's driver_info: ['ipmi_address'].                                                     |
+    +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
+
+#. If using API version 1.11 or above, the node was created in the ``enroll``
+   provision state. In order for the node to be available for deploying a
+   workload (for example, by the Compute service), it needs to be in the
+   ``available`` provision state. To do this, it must be moved into the
+   ``manageable`` state and then moved into the ``available`` state. The
+   `API version 1.11 and above`_ section describes the commands for this.
+
+.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter
+
+
+Enrolling a node
+----------------
+In the Liberty cycle, starting with API version 1.11, the Bare Metal service
+added a new initial provision state of ``enroll`` to its state machine.
+
+Existing automation tooling that use an API version lower than 1.11 are not
+affected, since the initial provision state is still ``available``.
+However, using API version 1.11 or above may break existing automation tooling
+with respect to node creation.
+
+The default API version used by (the most recent) python-ironicclient is 1.9.
+
+The examples below set the API version for each command. To set the
+API version for all commands, you can set the environment variable
+``IRONIC_API_VERSION``.
+
+API version 1.10 and below
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Below is an example of creating a node with API version 1.10. After creation,
+the node will be in the ``available`` provision state.
+Other API versions below 1.10 may be substituted in place of 1.10.
+
+::
+
+    ironic --ironic-api-version 1.10 node-create -d agent_ilo -n pre11
+
+    +--------------+--------------------------------------+
+    | Property     | Value                                |
+    +--------------+--------------------------------------+
+    | uuid         | cc4998a0-f726-4927-9473-0582458c6789 |
+    | driver_info  | {}                                   |
+    | extra        | {}                                   |
+    | driver       | agent_ilo                            |
+    | chassis_uuid |                                      |
+    | properties   | {}                                   |
+    | name         | pre11                                |
+    +--------------+--------------------------------------+
+
+
+    ironic --ironic-api-version 1.10 node-list
+
+    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
+    | UUID                                 | Name  | Instance UUID | Power State | Provisioning State | Maintenance |
+    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
+    | cc4998a0-f726-4927-9473-0582458c6789 | pre11 | None          | None        | available          | False       |
+    +--------------------------------------+-------+---------------+-------------+--------------------+-------------+
+
+API version 1.11 and above
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Beginning with API version 1.11, the initial provision state for newly created
+nodes is ``enroll``. In the examples below, other API versions above 1.11 may be
+substituted in place of 1.11.
+::
+
+    ironic --ironic-api-version 1.11 node-create -d agent_ilo -n post11
+
+    +--------------+--------------------------------------+
+    | Property     | Value                                |
+    +--------------+--------------------------------------+
+    | uuid         | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 |
+    | driver_info  | {}                                   |
+    | extra        | {}                                   |
+    | driver       | agent_ilo                            |
+    | chassis_uuid |                                      |
+    | properties   | {}                                   |
+    | name         | post11                               |
+    +--------------+--------------------------------------+
+
+
+    ironic --ironic-api-version 1.11 node-list
+
+    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
+    | UUID                                 | Name   | Instance UUID | Power State | Provisioning State | Maintenance |
+    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
+    | 0eb013bb-1e4b-4f4c-94b5-2e7468242611 | post11 | None          | None        | enroll             | False       |
+    +--------------------------------------+--------+---------------+-------------+--------------------+-------------+
+
+In order for nodes to be available for deploying workloads on them, nodes
+must be in the ``available`` provision state. To do this, nodes
+created with API version 1.11 and above must be moved from the ``enroll`` state
+to the ``manageable`` state and then to the ``available`` state.
+
+To move a node to a different provision state, use the
+``node-set-provision-state`` command.
+
+.. note:: Since it is an asychronous call, the response for
+          ``ironic node-set-provision-state`` will not indicate whether the
+          transition succeeded or not. You can check the status of the
+          operation via ``ironic node-show``. If it was successful,
+          ``provision_state`` will be in the desired state. If it failed,
+          there will be information in the node's ``last_error``.
+
+After creating a node and before moving it from its initial provision state of
+``enroll``, basic power and port information needs to be configured on the node.
+The Bare Metal service needs this information because it verifies that it is
+capable of controlling the node when transitioning the node from ``enroll`` to
+``manageable`` state.
+
+To move a node from ``enroll`` to ``manageable`` provision state::
+
+    ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage
+
+    ironic node-show $NODE_UUID
+
+    +------------------------+--------------------------------------------------------------------+
+    | Property               | Value                                                              |
+    +------------------------+--------------------------------------------------------------------+
+    | ...                    | ...                                                                |
+    | provision_state        | manageable                                                         | <- verify correct state
+    | uuid                   | 0eb013bb-1e4b-4f4c-94b5-2e7468242611                               |
+    | ...                    | ...                                                                |
+    +------------------------+--------------------------------------------------------------------+
+
+When a node is moved from the ``manageable`` to ``available`` provision
+state, the node will go through automated cleaning if configured to do so (see
+:ref:`configure-cleaning`).
+To move a node from ``manageable`` to ``available`` provision state::
+
+    ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID provide
+
+    ironic node-show $NODE_UUID
+
+    +------------------------+--------------------------------------------------------------------+
+    | Property               | Value                                                              |
+    +------------------------+--------------------------------------------------------------------+
+    | ...                    | ...                                                                |
+    | provision_state        | available                                                          | < - verify correct state
+    | uuid                   | 0eb013bb-1e4b-4f4c-94b5-2e7468242611                               |
+    | ...                    | ...                                                                |
+    +------------------------+--------------------------------------------------------------------+
+
+
+For more details on the Bare Metal service's state machine, see the
+`state machine <http://docs.openstack.org/developer/ironic/dev/states.html>`_
+documentation.
+
+
+Logical names
+-------------
+Beginning with the Kilo release a Node may also be referred to by a
+logical name as well as its UUID. Names can be assigned either when
+creating the node by adding the ``-n`` option to the ``node-create`` command or
+by updating an existing node with the ``node-update`` command.
+
+Node names must be unique, and conform to:
+
+- rfc952_
+- rfc1123_
+- wiki_hostname_
+
+The node is named 'example' in the following examples:
+::
+
+    ironic node-create -d agent_ipmitool -n example
+
+or::
+
+    ironic node-update $NODE_UUID add name=example
+
+
+Once assigned a logical name, a node can then be referred to by name or
+UUID interchangeably.
+::
+
+    ironic node-create -d agent_ipmitool -n example
+
+    +--------------+--------------------------------------+
+    | Property     | Value                                |
+    +--------------+--------------------------------------+
+    | uuid         | 71e01002-8662-434d-aafd-f068f69bb85e |
+    | driver_info  | {}                                   |
+    | extra        | {}                                   |
+    | driver       | agent_ipmitool                       |
+    | chassis_uuid |                                      |
+    | properties   | {}                                   |
+    | name         | example                              |
+    +--------------+--------------------------------------+
+
+
+    ironic node-show example
+
+    +------------------------+--------------------------------------+
+    | Property               | Value                                |
+    +------------------------+--------------------------------------+
+    | target_power_state     | None                                 |
+    | extra                  | {}                                   |
+    | last_error             | None                                 |
+    | updated_at             | 2015-04-24T16:23:46+00:00            |
+    | ...                    | ...                                  |
+    | instance_info          | {}                                   |
+    +------------------------+--------------------------------------+
+
+.. _rfc952: http://tools.ietf.org/html/rfc952
+.. _rfc1123: http://tools.ietf.org/html/rfc1123
+.. _wiki_hostname: http://en.wikipedia.org/wiki/Hostname
+
+
+Hardware Inspection
+-------------------
+
+Starting with the Kilo release, Bare Metal service supports hardware inspection
+that simplifies enrolling nodes - please see `inspection`_ for details.
+
+.. _`inspection`: http://docs.openstack.org/developer/ironic/deploy/inspection.html#inspection
diff --git a/install-guide/source/include/configure-neutron-networks.rst b/install-guide/source/include/configure-neutron-networks.rst
index 861580d45..0c2339a27 100644
--- a/install-guide/source/include/configure-neutron-networks.rst
+++ b/install-guide/source/include/configure-neutron-networks.rst
@@ -11,9 +11,7 @@ metal provisioning.
 You will also need to provide Bare Metal service with the MAC address(es) of
 each node that it is provisioning; Bare Metal service in turn will pass this
 information to Networking service for DHCP and PXE boot configuration.
-An example of this is shown in the `Enrollment`_ section.
-
-.. _`Enrollment`: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#enrollment
+An example of this is shown in the :ref:`enrollment` section.
 
 #. Edit ``/etc/neutron/plugins/ml2/ml2_conf.ini`` and modify these:
 
diff --git a/install-guide/source/index.rst b/install-guide/source/index.rst
index 112b08952..c49ceb78a 100644
--- a/install-guide/source/index.rst
+++ b/install-guide/source/index.rst
@@ -10,8 +10,9 @@ Bare Metal service
    configure-integration.rst
    configure-cleaning.rst
    configure-tenant-networks.rst
+   enrollment.rst
    advanced.rst
-   verify.rst
+   troubleshooting.rst
    next-steps.rst
 
 The Bare Metal service is a collection of components that provides support to
diff --git a/install-guide/source/troubleshooting.rst b/install-guide/source/troubleshooting.rst
new file mode 100644
index 000000000..7740f0e81
--- /dev/null
+++ b/install-guide/source/troubleshooting.rst
@@ -0,0 +1,126 @@
+.. _troubleshooting:
+
+===============
+Troubleshooting
+===============
+
+Once all the services are running and configured properly, and a node has been
+enrolled with the Bare Metal service and is in the ``available`` provision
+state, the Compute service should detect the node
+as an available resource and expose it to the scheduler.
+
+.. note::
+   There is a delay, and it may take up to a minute (one periodic task cycle)
+   for the Compute service to recognize any changes in the Bare Metal service's
+   resources (both additions and deletions).
+
+In addition to watching ``nova-compute`` log files, you can see the available
+resources by looking at the list of Compute hypervisors. The resources reported
+therein should match the bare metal node properties, and the Compute service flavor.
+
+Here is an example set of commands to compare the resources in Compute
+service and Bare Metal service::
+
+    $ ironic node-list
+    +--------------------------------------+---------------+-------------+--------------------+-------------+
+    | UUID                                 | Instance UUID | Power State | Provisioning State | Maintenance |
+    +--------------------------------------+---------------+-------------+--------------------+-------------+
+    | 86a2b1bb-8b29-4964-a817-f90031debddb | None          | power off   | available          | False       |
+    +--------------------------------------+---------------+-------------+--------------------+-------------+
+
+    $ ironic node-show 86a2b1bb-8b29-4964-a817-f90031debddb
+    +------------------------+----------------------------------------------------------------------+
+    | Property               | Value                                                                |
+    +------------------------+----------------------------------------------------------------------+
+    | instance_uuid          | None                                                                 |
+    | properties             | {u'memory_mb': u'1024', u'cpu_arch': u'x86_64', u'local_gb': u'10',  |
+    |                        | u'cpus': u'1'}                                                       |
+    | maintenance            | False                                                                |
+    | driver_info            | { [SNIP] }                                                           |
+    | extra                  | {}                                                                   |
+    | last_error             | None                                                                 |
+    | created_at             | 2014-11-20T23:57:03+00:00                                            |
+    | target_provision_state | None                                                                 |
+    | driver                 | pxe_ipmitool                                                         |
+    | updated_at             | 2014-11-21T00:47:34+00:00                                            |
+    | instance_info          | {}                                                                   |
+    | chassis_uuid           | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59                                 |
+    | provision_state        | available                                                            |
+    | reservation            | None                                                                 |
+    | power_state            | power off                                                            |
+    | console_enabled        | False                                                                |
+    | uuid                   | 86a2b1bb-8b29-4964-a817-f90031debddb                                 |
+    +------------------------+----------------------------------------------------------------------+
+
+    $ nova hypervisor-show 1
+    +-------------------------+--------------------------------------+
+    | Property                | Value                                |
+    +-------------------------+--------------------------------------+
+    | cpu_info                | baremetal cpu                        |
+    | current_workload        | 0                                    |
+    | disk_available_least    | -                                    |
+    | free_disk_gb            | 10                                   |
+    | free_ram_mb             | 1024                                 |
+    | host_ip                 | [ SNIP ]                             |
+    | hypervisor_hostname     | 86a2b1bb-8b29-4964-a817-f90031debddb |
+    | hypervisor_type         | ironic                               |
+    | hypervisor_version      | 1                                    |
+    | id                      | 1                                    |
+    | local_gb                | 10                                   |
+    | local_gb_used           | 0                                    |
+    | memory_mb               | 1024                                 |
+    | memory_mb_used          | 0                                    |
+    | running_vms             | 0                                    |
+    | service_disabled_reason | -                                    |
+    | service_host            | my-test-host                         |
+    | service_id              | 6                                    |
+    | state                   | up                                   |
+    | status                  | enabled                              |
+    | vcpus                   | 1                                    |
+    | vcpus_used              | 0                                    |
+    +-------------------------+--------------------------------------+
+
+.. _maintenance_mode:
+
+Maintenance mode
+----------------
+Maintenance mode may be used if you need to take a node out of the resource
+pool. Putting a node in maintenance mode will prevent Bare Metal service from
+executing periodic tasks associated with the node. This will also prevent
+Compute service from placing a tenant instance on the node by not exposing
+the node to the nova scheduler. Nodes can be placed into maintenance mode
+with the following command.
+::
+
+    $ ironic node-set-maintenance $NODE_UUID on
+
+As of the Kilo release, a maintenance reason may be included with the optional
+``--reason`` command line option. This is a free form text field that will be
+displayed in the ``maintenance_reason`` section of the ``node-show`` command.
+::
+
+    $ ironic node-set-maintenance $UUID on --reason "Need to add ram."
+
+    $ ironic node-show $UUID
+
+    +------------------------+--------------------------------------+
+    | Property               | Value                                |
+    +------------------------+--------------------------------------+
+    | target_power_state     | None                                 |
+    | extra                  | {}                                   |
+    | last_error             | None                                 |
+    | updated_at             | 2015-04-27T15:43:58+00:00            |
+    | maintenance_reason     | Need to add ram.                     |
+    | ...                    | ...                                  |
+    | maintenance            | True                                 |
+    | ...                    | ...                                  |
+    +------------------------+--------------------------------------+
+
+To remove maintenance mode and clear any ``maintenance_reason`` use the
+following command.
+::
+
+    $ ironic node-set-maintenance $NODE_UUID off
+
+
+.. _ironic-python-agent: http://docs.openstack.org/developer/ironic-python-agent/
diff --git a/install-guide/source/verify.rst b/install-guide/source/verify.rst
deleted file mode 100644
index 5a3b96278..000000000
--- a/install-guide/source/verify.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-.. _verify:
-
-================
-Verify operation
-================
-
-To verify the operation of the Bare Metal service, please see the
-`Troubleshooting`_ section of the legacy installation guide.
-
-.. _`Troubleshooting`: http://docs.openstack.org/developer/ironic/deploy/install-guide.html#troubleshooting