openstack/ironic
Code Issues Proposed changes

Merge "Refactor install-guide: update node enrollment"

Browse Source
This commit is contained in:
Jenkins 2017-05-18 13:25:56 +00:00 committed by Gerrit Code Review
commit ccffca15d4
1 changed files with 257 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

438
install-guide/source/enrollment.rst
View File

@ -25,20 +25,117 @@ they are in the ``available`` provision state.
"maintenance" mode. "maintenance" mode.
For more information see the :ref:`maintenance_mode` section. For more information see the :ref:`maintenance_mode` section.
Choosing a driver
-----------------
When enrolling a node, the most important information to supply is *driver*.
This can be either a *classic driver* or a *hardware type* - see
:doc:`enabling-drivers` for the difference. The ``driver-list`` command can
be used to list all drivers (of both types) enabled on all hosts:
.. code-block:: console
ironic driver-list
+---------------------+-----------------------+
| Supported driver(s) | Active host(s) |
+---------------------+-----------------------+
| ipmi | localhost.localdomain |
| pxe_ipmitool | localhost.localdomain |
+---------------------+-----------------------+
Starting with API version 1.31 (and ``python-ironicclient`` 1.13), you can
also list only classic or only dynamic drivers:
.. code-block:: console
ironic --ironic-api-version 1.31 driver-list -t dynamic
+---------------------+-----------------------+
| Supported driver(s) | Active host(s) |
+---------------------+-----------------------+
| ipmi | localhost.localdomain |
+---------------------+-----------------------+
The specific driver to use should be picked based on actual hardware
capabilities and expected features. See `driver-specific documentation`_
for more hints on that.
Each driver has a list of *driver properties* that need to be specified via
the node's ``driver_info`` field, in order for the driver to operate on node.
This list consists of the properties of the hardware interfaces that the driver
uses. These driver properties are available with the ``driver-properties``
command:
.. code-block:: console
$ 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. |
+----------------------+-------------------------------------------------------------------------------------------------------------+
The properties marked as required must be supplied either during node creation
or shortly after. Some properties may only be required for certain features.
.. _driver-specific documentation: https://docs.openstack.org/developer/ironic/deploy/drivers.html
Note on API versions
--------------------
Starting with API version 1.11, the Bare Metal service added a new initial
provision state of ``enroll`` to its state machine. When this or later API
version is used, new nodes get this state instead of ``available``.
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,
but it may change in the future and should not be relied on.
In the examples below we will use version 1.11 of the Bare metal API.
This gives us the following advantages:
* Explicit power credentials validation before leaving the ``enroll`` state.
* Running node cleaning before entering the ``available`` state.
* Not exposing half-configured nodes to the scheduler.
To set the API version for all commands, you can set the environment variable
``IRONIC_API_VERSION``. For the OpenStackClient baremetal plugin, set
the ``OS_BAREMETAL_API_VERSION`` variable to the same value. For example:
.. code-block:: console
$ export IRONIC_API_VERSION=1.11
$ export OS_BAREMETAL_API_VERSION=1.11
Enrollment process Enrollment process
------------------ ------------------
Creating a node
~~~~~~~~~~~~~~~
This section describes the main steps to enroll a node and make it available This section describes the main steps to enroll a node and make it available
for provisioning. Some steps are shown separately for illustration purposes, for provisioning. Some steps are shown separately for illustration purposes,
and may be combined if desired. and may be combined if desired.
#. Create a node in the Bare Metal service. At a minimum, you must #. Create a node in the Bare Metal service with the ``node-create`` command.
specify the driver name (for example, "pxe_ipmitool"). At a minimum, you must specify the driver name (for example,
This will return the node UUID along with other information ``pxe_ipmitool``, ``agent_ipmitool`` or ``ipmi``).
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 This command returns the node UUID along with other information
about the node. The node's provision state will be ``enroll``:
.. code-block:: console
$ export IRONIC_API_VERSION=1.11
$ ironic node-create -d pxe_ipmitool
+--------------+--------------------------------------+ +--------------+--------------------------------------+
| Property | Value | | Property | Value |
+--------------+--------------------------------------+ +--------------+--------------------------------------+
@ -51,7 +148,7 @@ and may be combined if desired.
| name | None | | name | None |
+--------------+--------------------------------------+ +--------------+--------------------------------------+
ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987 $ ironic node-show dfc6189f-ad83-4261-9bda-b27258eb1987
+------------------------+--------------------------------------+ +------------------------+--------------------------------------+
| Property | Value | | Property | Value |
+------------------------+--------------------------------------+ +------------------------+--------------------------------------+
@ -59,7 +156,7 @@ and may be combined if desired.
| extra | {} | | extra | {} |
| last_error | None | | last_error | None |
| maintenance_reason | None | | maintenance_reason | None |
| provision_state | available | | provision_state | enroll |
| uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 | | uuid | dfc6189f-ad83-4261-9bda-b27258eb1987 |
| console_enabled | False | | console_enabled | False |
| target_provision_state | None | | target_provision_state | None |
@ -79,81 +176,142 @@ and may be combined if desired.
option to the ``node-create`` command or by updating an existing node with option to the ``node-create`` command or by updating an existing node with
the ``node-update`` command. See `Logical Names`_ for examples. the ``node-update`` command. See `Logical Names`_ for examples.
Beginning with the API version 1.11 and above, a newly created node will #. Starting with API version 1.31 (and ``python-ironicclient`` 1.13), you can
have an initial provision state of ``enroll`` as opposed to pick which hardware interface to use with nodes that use hardware types.
``available``. See `Enrolling a node`_ for more details. Each interface is represented by a node field called ``<IFACE>_interface``
where ``<IFACE>`` in the interface type, e.g. ``boot``. See
:doc:`enabling-drivers` for details on hardware interfaces.
#. Update the node ``driver_info`` so that Bare Metal service can manage the An interface can be set either separately:
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 .. code-block:: console
+----------------------+-------------------------------------------------------------------------------------------------------------+
| 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 \ $ ironic --ironic-api-version 1.31 node-update $NODE_UUID replace \
driver_info/ipmi_username=$USER \ deploy_interface=direct \
driver_info/ipmi_password=$PASS \ raid_interface=agent
driver_info/ipmi_address=$ADDRESS
or set during node creation:
.. code-block:: console
$ ironic --ironic-api-version 1.31 node-create -d ipmi \
--deploy-interface direct \
--raid-interface agent
It's an error to try changing this field for a node with a *classic driver*,
and setting node's driver to classic one causes these fields to be set
to ``None`` automatically.
#. Update the node ``driver_info`` with the required driver properties, so that
the Bare Metal service can manage the node:
.. code-block:: console
$ ironic node-update $NODE_UUID add \
driver_info/ipmi_username=$USER \
driver_info/ipmi_password=$PASS \
driver_info/ipmi_address=$ADDRESS
.. note:: .. note::
If IPMI is running on a port other than 623 (the default). The port must 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. be added to ``driver_info`` by specifying the ``ipmi_port`` value.
Example:: Example:
ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER .. code-block:: console
Note that you may also specify all ``driver_info`` parameters during $ ironic node-update $NODE_UUID add driver_info/ipmi_port=$PORT_NUMBER
``node-create`` by passing the **-i** option multiple times.
You may also specify all ``driver_info`` parameters during node
creation by passing the **-i** option multiple times:
.. code-block:: console
$ ironic node-create -d pxe_ipmitool \
-i ipmi_username=$USER \
-i ipmi_password=$PASS \
-i ipmi_address=$ADDRESS
See `Choosing a driver`_ above for details on driver properties.
#. Update the node's properties to match the bare metal flavor you created #. Update the node's properties to match the bare metal flavor you created
earlier:: when :doc:`configure-nova-flavors`:
ironic node-update $NODE_UUID add \ .. code-block:: console
properties/cpus=$CPU \
properties/memory_mb=$RAM_MB \ $ ironic node-update $NODE_UUID add \
properties/local_gb=$DISK_GB \ properties/cpus=$CPU_COUNT \
properties/cpu_arch=$ARCH 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** As above, these can also be specified at node creation by passing the **-p**
option to ``node-create`` multiple times. option to ``node-create`` multiple times:
.. code-block:: console
$ ironic node-create -d pxe_ipmitool \
-i ipmi_username=$USER \
-i ipmi_password=$PASS \
-i ipmi_address=$ADDRESS \
-p cpus=$CPU_COUNT \
-p memory_mb=$RAM_MB \
-p local_gb=$DISK_GB \
-p cpu_arch=$ARCH
These values can also be discovered during `Hardware Inspection`_.
.. warning::
The value provided for the ``local_gb`` property must match the size of
the root device you're going to deploy on. By default
**ironic-python-agent** picks the smallest disk which is not smaller
than 4 GiB.
If you override this logic by using root device hints (see
:ref:`root-device-hints`), the ``local_gb`` value should match the size
of picked target disk.
.. TODO(dtantsur): cover resource classes
#. As mentioned in the :ref:`flavor-creation` section, you should specify
a deploy kernel and ramdisk compatible with the node's driver, for example:
.. code-block:: console
$ ironic node-update $NODE_UUID add \
driver_info/deploy_kernel=$DEPLOY_VMLINUZ_UUID \
driver_info/deploy_ramdisk=$DEPLOY_INITRD_UUID
#. You must also inform the 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:
.. code-block:: console
$ ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
#. If you wish to perform more advanced scheduling of the instances based on #. 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 hardware capabilities, you may add metadata to each node that will be
exposed to the nova scheduler (see: `ComputeCapabilitiesFilter`_). A full exposed to the the Compute scheduler (see: `ComputeCapabilitiesFilter`_).
explanation of this is outside of the scope of this document. It can be done A full explanation of this is outside of the scope of this document. It can
through the special ``capabilities`` member of node properties:: be done through the special ``capabilities`` member of node properties:
ironic node-update $NODE_UUID add \ .. code-block:: console
properties/capabilities=key1:val1,key2:val2
#. As mentioned in the :ref:`flavor-creation` section, you should specify $ ironic node-update $NODE_UUID add \
a deploy kernel and ramdisk compatible with the node's driver, for example:: properties/capabilities=key1:val1,key2:val2
ironic node-update $NODE_UUID add \ Some capabilities can also be discovered during `Hardware Inspection`_.
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 Validating node information
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 #. To check if Bare Metal service has the minimum information necessary for
a node's driver to function, you may ``validate`` it:: a node's driver to be functional, you may ``validate`` it:
ironic node-validate $NODE_UUID .. code-block:: console
$ ironic node-validate $NODE_UUID
+------------+--------+--------+ +------------+--------+--------+
| Interface | Result | Reason | | Interface | Result | Reason |
+------------+--------+--------+ +------------+--------+--------+
@ -163,11 +321,12 @@ and may be combined if desired.
| power | True | | | power | True | |
+------------+--------+--------+ +------------+--------+--------+
If the node fails validation, each driver will return information as to why If the node fails validation, each driver interface will return information
it failed:: as to why it failed:
ironic node-validate $NODE_UUID .. code-block:: console
$ ironic node-validate $NODE_UUID
+------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
| Interface | Result | Reason | | Interface | Result | Reason |
+------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+ +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
@ -181,10 +340,11 @@ and may be combined if desired.
ignore the deploy interface's validation error due to lack of image ignore the deploy interface's validation error due to lack of image
information. You may continue the enrollment process. This information will information. You may continue the enrollment process. This information will
be set by the Compute Service just before deploying, when an instance is be set by the Compute Service just before deploying, when an instance is
requested:: requested:
ironic node-validate $NODE_UUID .. code-block:: console
$ ironic node-validate $NODE_UUID
+------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Interface | Result | Reason | | Interface | Result | Reason |
+------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@ -194,109 +354,15 @@ and may be combined if desired.
| power | True | | | power | True | |
+------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
#. If using API version 1.11 or above, the node was created in the ``enroll`` Making node available for deployment
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
----------------
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 In order for nodes to be available for deploying workloads on them, nodes
must be in the ``available`` provision state. To do this, 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 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 the ``manageable`` state and then to the ``available`` state.
This section can be safely skipped, if API version 1.10 or earlier is used
To move a node to a different provision state, use the (which is the case by default).
``node-set-provision-state`` command.
.. note:: Since it is an asynchronous 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 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. ``enroll``, basic power and port information needs to be configured on the node.
@ -304,12 +370,12 @@ 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 capable of controlling the node when transitioning the node from ``enroll`` to
``manageable`` state. ``manageable`` state.
To move a node from ``enroll`` to ``manageable`` provision state:: To move a node from ``enroll`` to ``manageable`` provision state:
ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage .. code-block:: console
ironic node-show $NODE_UUID
$ ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID manage
$ ironic node-show $NODE_UUID
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
| Property | Value | | Property | Value |
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
@ -319,15 +385,23 @@ To move a node from ``enroll`` to ``manageable`` provision state::
| ... | ... | | ... | ... |
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
.. note:: Since it is an asynchronous 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``.
When a node is moved from the ``manageable`` to ``available`` provision 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 state, the node will go through automated cleaning if configured to do so (see
:ref:`configure-cleaning`). :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 To move a node from ``manageable`` to ``available`` provision state:
ironic node-show $NODE_UUID .. code-block:: console
$ ironic --ironic-api-version 1.11 node-set-provision-state $NODE_UUID provide
$ ironic node-show $NODE_UUID
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
| Property | Value | | Property | Value |
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
@ -337,16 +411,17 @@ To move a node from ``manageable`` to ``available`` provision state::
| ... | ... | | ... | ... |
+------------------------+--------------------------------------------------------------------+ +------------------------+--------------------------------------------------------------------+
For more details on the Bare Metal service's state machine, see the For more details on the Bare Metal service's state machine, see the
`state machine <http://docs.openstack.org/developer/ironic/dev/states.html>`_ `state machine <http://docs.openstack.org/developer/ironic/dev/states.html>`_
documentation. documentation.
.. _ComputeCapabilitiesFilter: http://docs.openstack.org/developer/nova/devref/filter_scheduler.html?highlight=computecapabilitiesfilter
Logical names Logical names
------------- -------------
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`` A node may also be referred to by a logical name as well as its UUID.
Names can be assigned either during its creation by adding the ``-n``
option to the ``node-create`` command or by updating an existing node with option to the ``node-create`` command or by updating an existing node with
the ``node-update`` command. the ``node-update`` command.
@ -357,21 +432,24 @@ Node names must be unique, and conform to:
- wiki_hostname_ - wiki_hostname_
The node is named 'example' in the following examples: The node is named 'example' in the following examples:
::
ironic node-create -d agent_ipmitool -n example .. code-block:: console
or:: $ ironic node-create -d agent_ipmitool -n example
ironic node-update $NODE_UUID add name=example or
.. code-block:: console
$ ironic node-update $NODE_UUID add name=example
Once assigned a logical name, a node can then be referred to by name or Once assigned a logical name, a node can then be referred to by name or
UUID interchangeably. UUID interchangeably:
::
ironic node-create -d agent_ipmitool -n example .. code-block:: console
$ ironic node-create -d agent_ipmitool -n example
+--------------+--------------------------------------+ +--------------+--------------------------------------+
| Property | Value | | Property | Value |
+--------------+--------------------------------------+ +--------------+--------------------------------------+
@ -384,9 +462,7 @@ UUID interchangeably.
| name | example | | name | example |
+--------------+--------------------------------------+ +--------------+--------------------------------------+
$ ironic node-show example
ironic node-show example
+------------------------+--------------------------------------+ +------------------------+--------------------------------------+
| Property | Value | | Property | Value |
+------------------------+--------------------------------------+ +------------------------+--------------------------------------+