From 9639ec3728925980d6e90a4b808a6c2079c0785f Mon Sep 17 00:00:00 2001 From: Ruby Loo Date: Tue, 1 Sep 2015 18:39:33 +0000 Subject: [PATCH] Document nodes in enroll state, in install guide API version 1.11 introduced the 'enroll' initial provision state. This adds documentation to the install guide, on how to enroll a node using an API version below 1.11 as well as using an API version of 1.11 or above. Change-Id: I97e2a40308dc994986b60fc6b961c2c553e4e890 Co-Authored-By: Chris Krelle --- doc/source/deploy/install-guide.rst | 235 +++++++++++++++++++++++++--- 1 file changed, 209 insertions(+), 26 deletions(-) diff --git a/doc/source/deploy/install-guide.rst b/doc/source/deploy/install-guide.rst index e4fc797f7d..33dd6fa500 100644 --- a/doc/source/deploy/install-guide.rst +++ b/doc/source/deploy/install-guide.rst @@ -1309,13 +1309,14 @@ Enrollment ========== After all the services have been properly configured, you should enroll your -hardware with Bare Metal service, and confirm that the Compute service sees -the available hardware. +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:: - When enrolling nodes with Bare Metal service, note that the Compute service - will not be immediately notified of the new resources. Compute service's - resource tracker syncs periodically, and so any changes made directly to + 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. @@ -1324,16 +1325,23 @@ the available hardware. 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 nova scheduler, for instance so that you - can perform maintenance on it, you can set the node to "maintenance" mode. + 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. -Some steps are shown separately for illustration purposes, and may be combined -if desired. +Enrollment process +------------------ -#. Create a node in the Bare Metal service. At minimum, you must +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:: + 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 +--------------+--------------------------------------+ @@ -1348,6 +1356,29 @@ if desired. | 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 @@ -1355,6 +1386,10 @@ if desired. 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:: @@ -1429,22 +1464,169 @@ if desired. | power | True | | +------------+--------+--------+ - If the node fails validation, each driver will return information as to why it failed:: + If the node fails validation, each driver will return information as to why + it failed:: - ironic node-validate $NODE_UUID + 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']. | - +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ + +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ + | 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 be cleaned 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 `_ +documentation. + + Logical names ------------- Beginning with the Kilo release a Node may also be referred to by a @@ -1988,13 +2170,14 @@ disk-image-builder Troubleshooting =============== -Once all the services are running and configured properly, and a node is -enrolled with Bare Metal service, the Compute service should detect the node +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 Bare Metal service's + 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 @@ -2008,7 +2191,7 @@ service and Bare Metal service:: +--------------------------------------+---------------+-------------+--------------------+-------------+ | UUID | Instance UUID | Power State | Provisioning State | Maintenance | +--------------------------------------+---------------+-------------+--------------------+-------------+ - | 86a2b1bb-8b29-4964-a817-f90031debddb | None | power off | None | False | + | 86a2b1bb-8b29-4964-a817-f90031debddb | None | power off | available | False | +--------------------------------------+---------------+-------------+--------------------+-------------+ $ ironic node-show 86a2b1bb-8b29-4964-a817-f90031debddb @@ -2028,7 +2211,7 @@ service and Bare Metal service:: | updated_at | 2014-11-21T00:47:34+00:00 | | instance_info | {} | | chassis_uuid | 7b49bbc5-2eb7-4269-b6ea-3f1a51448a59 | - | provision_state | None | + | provision_state | available | | reservation | None | | power_state | power off | | console_enabled | False |