Enrollment¶

Creating a node¶

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.

1. Create a node in the Bare Metal service with the node-create command. At a minimum, you must specify the driver name (for example, pxe_ipmitool, agent_ipmitool or ipmi).

   This command returns the node UUID along with other information about the node. The node’s provision state will be enroll:

   $ export IRONIC_API_VERSION=1.11
   $ 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        | enroll                               |
   | 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            | {}                                   |
   | ...                    | ...                                  |
   +------------------------+--------------------------------------+
   

   A node may also be referred to by a logical name as well as its UUID. A name can be assigned to the node during its creation 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.

2. Starting with API version 1.31 (and python-ironicclient 1.13), you can pick which hardware interface to use with nodes that use hardware types. Each interface is represented by a node field called <IFACE>_interface where <IFACE> in the interface type, e.g. boot. See Enabling drivers and hardware types for details on hardware interfaces and Upgrading to Hardware Types for the matching between classic drivers and hardware types.

   An interface can be set either separately:

   $ ironic --ironic-api-version 1.31 node-update $NODE_UUID replace \
       deploy_interface=direct \
       raid_interface=agent
   

   or set during node creation:

   $ ironic --ironic-api-version 1.31 node-create -d ipmi \
       --deploy-interface direct \
       --raid-interface agent
   

   If no value is provided for some interfaces, Defaults for hardware interfaces are used instead.

   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.

3. Update the node driver_info with the required driver properties, so that the Bare Metal service can manage the node:

   $ 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
   

   You may also specify all driver_info parameters during node creation by passing the -i option multiple times:

   $ 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.

4. Specify a deploy kernel and ramdisk compatible with 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
   

   See Create and add images to the Image service for details.

5. 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:

   $ ironic port-create -n $NODE_UUID -a $MAC_ADDRESS
   

Adding scheduling information¶

1. Assign a resource class to the node. A resource class should represent a class of hardware in your data center, that corresponds to a Compute flavor.

   For example, let’s split hardware into these three groups:

   1. nodes with a lot of RAM and powerful CPU for computational tasks,
   2. nodes with powerful GPU for OpenCL computing,
   3. smaller nodes for development and testing.

   We can define three resource classes to reflect these hardware groups, named large-cpu, large-gpu and small respectively. Then, for each node in each of the hardware groups, we’ll set their resource_class appropriately via:

   $ openstack --os-baremetal-api-version 1.21 baremetal node set $NODE_UUID \
       --resource-class $CLASS_NAME
   

   The --resource-class argument can also be used when creating a node:

   $ openstack --os-baremetal-api-version 1.21 baremetal node create \
       --driver $DRIVER --resource-class $CLASS_NAME
   

   To use resource classes for scheduling you need to update your flavors as described in Create flavors for use with the Bare Metal service.

   Warning

   Scheduling based on resource classes will replace scheduling based on properties in the Queens release.

   Note

   This is not required for standalone deployments, only for those using the Compute service for provisioning bare metal instances.

2. Update the node’s properties to match the actual hardware of the node:

   $ ironic node-update $NODE_UUID add \
       properties/cpus=$CPU_COUNT \
       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:

   $ 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

   If scheduling based on resource classes is not used, the three properties cpus, memory_mb and local_gb must match ones defined on the flavor created when Create flavors for use with the Bare Metal service.

   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 Specifying the disk for deployment (root device hints)), the local_gb value should match the size of picked target disk.

3. 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 the Compute 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
   

   Some capabilities can also be discovered during Hardware Inspection.

Validating node information¶

1. To check if Bare Metal service has the minimum information necessary for a node’s driver to be functional, 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 interface 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'].                                                     |
   +------------+--------+-------------------------------------------------------------------------------------------------------------------------------------+
   

   When using the Compute Service with the Bare Metal service, it is safe to ignore the deploy interface’s validation error due to lack of image information. You may continue the enrollment process. This information will be set by the Compute Service just before deploying, when an instance is requested:

   $ ironic node-validate $NODE_UUID
   +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | Interface  | Result | Reason                                                                                                                                                           |
   +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   | console    | True   |                                                                                                                                                                  |
   | deploy     | False  | Cannot validate image information for node because one or more parameters are missing from its instance_info. Missing are: ['ramdisk', 'kernel', 'image_source'] |
   | management | True   |                                                                                                                                                                  |
   | power      | True   |                                                                                                                                                                  |
   +------------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   

Making node available for deployment¶

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. This section can be safely skipped, if API version 1.10 or earlier is used (which is the case by default).

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 Configure the Bare Metal service for 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 Ironic’s State Machine documentation.

Mapping nodes to Compute cells¶

If the Compute service is used for scheduling, and the discover_hosts_in_cells_interval was not set as described in Configure the Compute service to use the Bare Metal service, then log into any controller node and run the following command to map the new node(s) to Compute cells:

nova-manage cell_v2 discover_hosts

Example¶

Consider the following configuration (shortened for simplicity):

[DEFAULT]
enabled_hardware_types = ipmi,redfish
enabled_console_interfaces = no-console,ipmitool-shellinabox
enabled_deploy_interfaces = iscsi,direct
enabled_management_interfaces = ipmitool,redfish
enabled_power_interfaces = ipmitool,redfish
default_deploy_interface = direct

A new node is created with the ipmi driver and no interfaces specified:

$ export IRONIC_API_VERSION=1.31
$ ironic node-create -d ipmi
+--------------+--------------------------------------+
| Property     | Value                                |
+--------------+--------------------------------------+
| uuid         | dfc6189f-ad83-4261-9bda-b27258eb1987 |
| driver_info  | {}                                   |
| extra        | {}                                   |
| driver       | ipmi                                 |
| chassis_uuid |                                      |
| properties   | {}                                   |
| name         | None                                 |
+--------------+--------------------------------------+

Then the defaults for the interfaces that will be used by the node in this example are calculated as follows:

deploy

An explicit value of direct is provided for default_deploy_interface, so it is used.

power

No default is configured. The ipmi hardware type supports only ipmitool power. The intersection between supported power interfaces and values provided in the enabled_power_interfaces option has only one item: ipmitool. It is used.

console

No default is configured. The ipmi hardware type supports the following console interfaces: ipmitool-socat, ipmitool-shellinabox and no-console (in this order). Of these three, only two are enabled: no-console and ipmitool-shellinabox (order does not matter). The intersection contains ipmitool-shellinabox and no-console. The first item is used, and it is ipmitool-shellinabox.

management

Following the same calculation as power, the ipmitool management interface is used.