From 0445213bbbaca44346e4d1160134ae1ac57bd049 Mon Sep 17 00:00:00 2001
From: Mathieu Mitchell <mmitchell@iweb.com>
Date: Tue, 13 Sep 2016 21:56:08 -0400
Subject: [PATCH] [install-guide] Import "Enrollment" and "Troubleshooting"
sections
Change-Id: Ie8b570d2a54c38a9d04976a0430fe0d963db57b0
Partial-bug: #1612278
---
doc/source/deploy/install-guide.rst | 517 +-----------------
install-guide/source/enrollment.rst | 398 ++++++++++++++
.../include/configure-neutron-networks.rst | 4 +-
install-guide/source/index.rst | 3 +-
install-guide/source/troubleshooting.rst | 126 +++++
install-guide/source/verify.rst | 10 -
6 files changed, 535 insertions(+), 523 deletions(-)
create mode 100644 install-guide/source/enrollment.rst
create mode 100644 install-guide/source/troubleshooting.rst
delete mode 100644 install-guide/source/verify.rst
diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst
index 0e955069df..5a2f5ba139 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.
+The `Enrollment`_ section has been moved to the Bare Metal service Install
+Guide.
-.. 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
--------------------
-
-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.
+The `Troubleshooting`_ section has been moved to the Bare Metal service Install
+Guide.
-.. 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
-
-
-.. _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 0000000000..49ff012d3c
--- /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 861580d451..0c2339a27f 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 112b089529..c49ceb78ab 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 0000000000..7740f0e81a
--- /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 5a3b96278a..0000000000
--- 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