392 lines
13 KiB
ReStructuredText
392 lines
13 KiB
ReStructuredText
===============
|
|
Node Deployment
|
|
===============
|
|
|
|
.. contents::
|
|
:depth: 2
|
|
|
|
Overview
|
|
========
|
|
|
|
Node deployment is performed by the Bare Metal service to prepare a node for
|
|
use by a workload. The exact work flow used depends on a number of factors,
|
|
including the hardware type and interfaces assigned to a node.
|
|
|
|
Deploy Steps
|
|
============
|
|
|
|
The Bare Metal service implements deployment by collecting a list of deploy
|
|
steps to perform on a node from the Power, Deploy, Management, BIOS, and RAID
|
|
interfaces of the driver assigned to the node. These steps are then ordered by
|
|
priority and executed on the node when the node is moved to the ``deploying``
|
|
state.
|
|
|
|
Nodes move to the ``deploying`` state when attempting to move to the ``active``
|
|
state (when the hardware is prepared for use by a workload). For a full
|
|
understanding of all state transitions into deployment, please see
|
|
:doc:`/user/states`.
|
|
|
|
The Bare Metal service added support for deploy steps in the Rocky release.
|
|
|
|
Order of execution
|
|
------------------
|
|
|
|
Deploy steps are ordered from higher to lower priority, where a larger integer
|
|
is a higher priority. If the same priority is used by deploy steps on different
|
|
interfaces, the following resolution order is used: Power, Management, Deploy,
|
|
BIOS, and RAID interfaces.
|
|
|
|
.. _node-deployment-core-steps:
|
|
|
|
Agent steps
|
|
-----------
|
|
|
|
All deploy interfaces based on ironic-python-agent (i.e. ``direct``,
|
|
``ansible`` and any derivatives) expose the following deploy steps:
|
|
|
|
``deploy.deploy`` (priority 100)
|
|
In this step the node is booted using a provisioning image.
|
|
``deploy.write_image`` (priority 80)
|
|
An out-of-band (``ansible``) or in-band (``direct``) step that
|
|
downloads and writes the image to the node.
|
|
``deploy.tear_down_agent`` (priority 40)
|
|
In this step the provisioning image is shut down.
|
|
``deploy.switch_to_tenant_network`` (priority 30)
|
|
In this step networking for the node is switched from provisioning to
|
|
tenant networks.
|
|
``deploy.boot_instance`` (priority 20)
|
|
In this step the node is booted into the user image.
|
|
|
|
Additionally, the ``direct`` deploy interfaces has:
|
|
|
|
``deploy.prepare_instance_boot`` (priority 60)
|
|
In this step the boot device is configured and the bootloader is installed.
|
|
|
|
.. note::
|
|
For the ``ansible`` deploy interface these steps are done in
|
|
``deploy.write_image``.
|
|
|
|
Accordingly, the following priority ranges can be used for custom deploy steps:
|
|
|
|
> 100
|
|
Out-of-band steps to run before deployment.
|
|
81 to 99
|
|
In-band deploy steps to run before the image is written.
|
|
61 to 79
|
|
In-band deploy steps to run after the image is written but before the
|
|
bootloader is installed.
|
|
41 to 59
|
|
In-band steps to run after the image is written the bootloader is installed.
|
|
21 to 39
|
|
Out-of-band steps to run after the provisioning image is shut down.
|
|
1 to 19
|
|
Any steps that are run when the user instance is already running.
|
|
|
|
In-band steps
|
|
-------------
|
|
|
|
More deploy steps can be provided by the ramdisk, see
|
|
:ironic-python-agent-doc:`IPA hardware managers documentation
|
|
<admin/hardware_managers.html>` for a listing.
|
|
|
|
.. _standalone-deploy-steps:
|
|
|
|
Requesting steps
|
|
----------------
|
|
|
|
Starting with Bare Metal API version 1.69 user can optionally supply deploy
|
|
steps for node deployment when invoking deployment or rebuilding. Overlapping
|
|
steps will take precedence over `Agent steps`_ and `Deploy Templates`_
|
|
steps.
|
|
|
|
Using "baremetal" client deploy steps can be passed via ``--deploy-steps``
|
|
argument. The argument ``--deploy-steps`` is one of:
|
|
|
|
- a JSON string
|
|
- path to a JSON file whose contents are passed to the API
|
|
- '-', to read from stdin. This allows piping in the deploy steps.
|
|
|
|
An example by passing a JSON string:
|
|
|
|
.. code-block:: console
|
|
|
|
baremetal node deploy <node> \
|
|
--deploy-steps '[{"interface": "bios", "step": "apply_configuration", "args": {"settings": [{"name": "LogicalProc", "value": "Enabled"}]}, "priority": 150}]'
|
|
|
|
Format of JSON for deploy steps argument is described in `Deploy step format`_
|
|
section.
|
|
|
|
.. note::
|
|
Starting with `ironicclient` 4.6.0 you can provide a YAML file for
|
|
``--deploy-steps``.
|
|
|
|
Excluding the default steps
|
|
---------------------------
|
|
|
|
Starting with the Xena release, you can use the new :ref:`custom-agent-deploy`
|
|
interface to exclude the default step ``write_image`` and skip bootloader
|
|
installation in the ``prepare_instance_boot`` step.
|
|
|
|
Writing a Deploy Step
|
|
---------------------
|
|
|
|
Please refer to :doc:`/contributor/deploy-steps`.
|
|
|
|
FAQ
|
|
---
|
|
|
|
What deploy step is running?
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
To check what deploy step the node is performing or attempted to perform and
|
|
failed, run the following command; it will return the value in the node's
|
|
``driver_internal_info`` field::
|
|
|
|
baremetal node show <node> -f value -c driver_internal_info
|
|
|
|
The ``deploy_steps`` field will contain a list of all remaining steps with
|
|
their priorities, and the first one listed is the step currently in progress or
|
|
that the node failed before going into ``deploy failed`` state.
|
|
|
|
Troubleshooting
|
|
---------------
|
|
If deployment fails on a node, the node will be put into the ``deploy failed``
|
|
state until the node is deprovisioned. A deprovisioned node is moved to the
|
|
``available`` state after the cleaning process has been performed successfully.
|
|
|
|
Strategies for determining why a deploy step failed include checking the ironic
|
|
conductor logs, checking logs from the ironic-python-agent that have been
|
|
stored on the ironic conductor, or performing general hardware troubleshooting
|
|
on the node.
|
|
|
|
Deploy Templates
|
|
================
|
|
|
|
Starting with the Stein release, with Bare Metal API version 1.55, deploy
|
|
templates offer a way to define a set of one or more deploy steps to be
|
|
executed with particular sets of arguments and priorities.
|
|
|
|
Each deploy template has a name, which must be a valid trait. Traits can be
|
|
either standard or custom. Standard traits are listed in the
|
|
:os-traits-doc:`os_traits library <>`. Custom traits must
|
|
meet the following requirements:
|
|
|
|
* prefixed with ``CUSTOM_``
|
|
* contain only upper case characters A to Z, digits 0 to 9, or underscores
|
|
* no longer than 255 characters in length
|
|
|
|
Deploy step format
|
|
------------------
|
|
|
|
An invocation of a deploy step is defined in a deploy template as follows::
|
|
|
|
{
|
|
"interface": "<name of the driver interface>",
|
|
"step": "<name of the step>",
|
|
"args": {
|
|
"<arg1>": "<value1>",
|
|
"<arg2>": "<value2>"
|
|
},
|
|
"priority": <priority of the step>
|
|
}
|
|
|
|
A deploy template contains a list of one or more such steps. Each combination
|
|
of `interface` and `step` may only be specified once in a deploy template.
|
|
|
|
Matching deploy templates
|
|
-------------------------
|
|
|
|
During deployment, if any of the traits in a node's ``instance_info.traits``
|
|
field match the name of a deploy template, then the steps from that deploy
|
|
template will be added to the list of steps to be executed by the node.
|
|
|
|
When using the Compute service, any traits in the instance's flavor properties
|
|
or image properties are stored in ``instance_info.traits`` during deployment.
|
|
See :ref:`scheduling-traits` for further information on how traits are used for
|
|
scheduling when the Bare Metal service is used with the Compute service.
|
|
|
|
Note that there is no ongoing relationship between a node and any templates
|
|
that are matched during deployment. The set of matching deploy templates is
|
|
checked at deployment time. Any subsequent updates to or deletion of those
|
|
templates will not be reflected in the node's configuration unless it is
|
|
redeployed or rebuilt. Similarly, if a node is rebuilt and the set of matching
|
|
deploy templates has changed since the initial deployment, then the resulting
|
|
configuration of the node may be different from the initial deployment.
|
|
|
|
Overriding default deploy steps
|
|
-------------------------------
|
|
|
|
A deploy step is enabled by default if it has a non-zero default priority.
|
|
A default deploy step may be overridden in a deploy template. If the step's
|
|
priority is a positive integer it will be executed with the specified priority
|
|
and arguments. If the step's priority is zero, the step will not be executed.
|
|
|
|
If the :ref:`deploy.deploy step <node-deployment-core-steps>` is included in a
|
|
deploy template, it can only be assigned a priority of zero to disable it.
|
|
|
|
Creating a deploy template via API
|
|
----------------------------------
|
|
|
|
A deploy template can be created using the Bare Metal API::
|
|
|
|
POST /v1/deploy_templates
|
|
|
|
Here is an example of the body of a request to create a deploy template with a
|
|
single step:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"name": "CUSTOM_HYPERTHREADING_ON",
|
|
"steps": [
|
|
{
|
|
"interface": "bios",
|
|
"step": "apply_configuration",
|
|
"args": {
|
|
"settings": [
|
|
{
|
|
"name": "LogicalProc",
|
|
"value": "Enabled"
|
|
}
|
|
]
|
|
},
|
|
"priority": 150
|
|
}
|
|
]
|
|
}
|
|
|
|
Further information on this API is available `here
|
|
<https://docs.openstack.org/api-ref/baremetal/index.html?expanded=create-deploy-template-detail#create-deploy-template>`__.
|
|
|
|
Creating a deploy template via "baremetal" client
|
|
-----------------------------------------------------------
|
|
|
|
A deploy template can be created via the ``baremetal deploy template
|
|
create`` command, starting with ``python-ironicclient`` 2.7.0.
|
|
|
|
The argument ``--steps`` must be specified. Its value is one of:
|
|
|
|
- a JSON string
|
|
- path to a JSON file whose contents are passed to the API
|
|
- '-', to read from stdin. This allows piping in the deploy steps.
|
|
|
|
Example of creating a deploy template with a single step using a JSON string:
|
|
|
|
.. code-block:: console
|
|
|
|
baremetal deploy template create \
|
|
CUSTOM_HYPERTHREADING_ON \
|
|
--steps '[{"interface": "bios", "step": "apply_configuration", "args": {"settings": [{"name": "LogicalProc", "value": "Enabled"}]}, "priority": 150}]'
|
|
|
|
Or with a file:
|
|
|
|
.. code-block:: console
|
|
|
|
baremetal deploy template create \
|
|
CUSTOM_HYPERTHREADING_ON \
|
|
---steps my-deploy-steps.txt
|
|
|
|
Or with stdin:
|
|
|
|
.. code-block:: console
|
|
|
|
cat my-deploy-steps.txt | baremetal deploy template create \
|
|
CUSTOM_HYPERTHREADING_ON \
|
|
--steps -
|
|
|
|
Example of use with the Compute service
|
|
---------------------------------------
|
|
|
|
.. note:: The deploy steps used in this example are for example purposes only.
|
|
|
|
In the following example, we first add the trait ``CUSTOM_HYPERTHREADING_ON``
|
|
to the node represented by ``<node>``:
|
|
|
|
.. code-block:: console
|
|
|
|
baremetal node add trait <node> CUSTOM_HYPERTHREADING_ON
|
|
|
|
We also update the flavor ``bm-hyperthreading-on`` in the Compute
|
|
service with the following property:
|
|
|
|
.. code-block:: console
|
|
|
|
openstack flavor set --property trait:CUSTOM_HYPERTHREADING_ON=required bm-hyperthreading-on
|
|
|
|
Creating a Compute instance with this flavor will ensure that the instance is
|
|
scheduled only to Bare Metal nodes with the ``CUSTOM_HYPERTHREADING_ON`` trait.
|
|
|
|
We could then create a Bare Metal deploy template with the name
|
|
``CUSTOM_HYPERTHREADING_ON`` and a deploy step that enables Hyperthreading:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"name": "CUSTOM_HYPERTHREADING_ON",
|
|
"steps": [
|
|
{
|
|
"interface": "bios",
|
|
"step": "apply_configuration",
|
|
"args": {
|
|
"settings": [
|
|
{
|
|
"name": "LogicalProc",
|
|
"value": "Enabled"
|
|
}
|
|
]
|
|
},
|
|
"priority": 150
|
|
}
|
|
]
|
|
}
|
|
|
|
When an instance is created using the ``bm-hyperthreading-on`` flavor, then the
|
|
deploy steps of deploy template ``CUSTOM_HYPERTHREADING_ON`` will be executed
|
|
during the deployment of the scheduled node, causing Hyperthreading to be
|
|
enabled in the node's BIOS configuration.
|
|
|
|
To make this example more dynamic, let's add a second trait
|
|
``CUSTOM_HYPERTHREADING_OFF`` to the node:
|
|
|
|
.. code-block:: console
|
|
|
|
baremetal node add trait <node> CUSTOM_HYPERTHREADING_OFF
|
|
|
|
We could also update a second flavor, ``bm-hyperthreading-off``, with the
|
|
following property:
|
|
|
|
.. code-block:: console
|
|
|
|
openstack flavor set --property trait:CUSTOM_HYPERTHREADING_OFF=required bm-hyperthreading-off
|
|
|
|
Finally, we create a deploy template with the name
|
|
``CUSTOM_HYPERTHREADING_OFF`` and a deploy step that disables Hyperthreading:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"name": "CUSTOM_HYPERTHREADING_OFF",
|
|
"steps": [
|
|
{
|
|
"interface": "bios",
|
|
"step": "apply_configuration",
|
|
"args": {
|
|
"settings": [
|
|
{
|
|
"name": "LogicalProc",
|
|
"value": "Disabled"
|
|
}
|
|
]
|
|
},
|
|
"priority": 150
|
|
}
|
|
]
|
|
}
|
|
|
|
Creating a Compute instance with the ``bm-hyperthreading-off`` instance will
|
|
cause the scheduled node to have Hyperthreading disabled in the BIOS during
|
|
deployment.
|
|
|
|
We now have a way to create Compute instances with different configurations, by
|
|
choosing between different Compute flavors, supported by a single Bare Metal
|
|
node that is dynamically configured during deployment.
|