582b2e991c
Implement cross-referencing to configuration options through out the Ironic documentation. Closes-Bug: #2076111 Change-Id: I28712a3a92eb7e7d9875e49ea3ed8800168262fe
229 lines
7.1 KiB
ReStructuredText
229 lines
7.1 KiB
ReStructuredText
.. _servicing:
|
|
|
|
==============
|
|
Node servicing
|
|
==============
|
|
|
|
Overview
|
|
========
|
|
|
|
In order to better enable operators to modify existing nodes, Ironic has
|
|
introduced the model of Node Servicing, where you can take a node in
|
|
``active`` state, modify it using steps similar to Deploy Steps or manual
|
|
cleaning through the Cleaning subsystem.
|
|
|
|
For more information on cleaning, please see :ref:`cleaning`.
|
|
|
|
Major differences
|
|
=================
|
|
|
|
Service steps do not contain an automatic execution model, which is intrinisc
|
|
to the standard deployment and "automated" cleaning workflows. This *may*
|
|
change at some point in the future.
|
|
|
|
This also means that while a priority value *can* be supplied, it is not
|
|
presently utilized.
|
|
|
|
Similarities to Cleaning and Deployment
|
|
=======================================
|
|
|
|
Similar to Clean and Deploy steps, when invoked an operator can validate
|
|
the current running steps by viewing the ``driver_internal_info`` field
|
|
looking for a ``service_steps`` field. The *current* step being executed
|
|
can be viewed using the baremetal node ``service_step`` field, which is a
|
|
top level field.
|
|
|
|
Service steps are internally decorated on driver interface methods utilizing
|
|
decorator. This means service steps do not *automatically* expose clean and
|
|
deploy steps to be executed at any time. The Ironic development team took a
|
|
cautious and intentional approach behind methods which are decorated. Besides,
|
|
some clean and deployment steps are geared explicitly for operating in
|
|
that mode, and would not be suitable to be triggered outside of the
|
|
original workflow it was designed for use in.
|
|
|
|
Available Steps
|
|
===============
|
|
|
|
|
|
Executing Service Steps
|
|
=======================
|
|
|
|
In order for manual cleaning to work, you may need to configure a
|
|
`Servicing Network`_.
|
|
|
|
Starting manual servicing via API
|
|
---------------------------------
|
|
|
|
Servicing can only be performed when a node is in the ``active``
|
|
provision state. The REST API request to initiate it is available in
|
|
API version 1.87 and higher::
|
|
|
|
PUT /v1/nodes/<node_ident>/states/provision
|
|
|
|
(Additional information is available `here <https://docs.openstack.org/api-ref/baremetal/index.html?expanded=change-node-provision-state-detail#change-node-provision-state>`_.)
|
|
|
|
This API will allow operators to put a node directly into ``servicing``
|
|
provision state from ``active`` provision state via 'target': 'service'.
|
|
The PUT will also require the argument 'service_steps' to be specified. This
|
|
is an ordered list of steps. A step is represented by a
|
|
dictionary (JSON), in the form::
|
|
|
|
{
|
|
"interface": "<interface>",
|
|
"step": "<name of step>",
|
|
"args": {"<arg1>": "<value1>", ..., "<argn>": <valuen>}
|
|
}
|
|
|
|
The 'interface' and 'step' keys are required for all steps. If a servicing step
|
|
method takes keyword arguments, the 'args' key may be specified. It
|
|
is a dictionary of keyword variable arguments, with each keyword-argument entry
|
|
being <name>: <value>.
|
|
|
|
If any step is missing a required keyword argument, servicing will not be
|
|
performed and the node will be put in ``service failed`` provision state
|
|
with an appropriate error message.
|
|
|
|
If, during the servicing process, a service step determines that it has
|
|
incorrect keyword arguments, all earlier steps will be performed and then the
|
|
node will be put in ``service failed`` provision state with an appropriate
|
|
error message.
|
|
|
|
An example of the request body for this API::
|
|
|
|
{
|
|
"target":"service",
|
|
"sevice_steps": [{
|
|
"interface": "raid",
|
|
"step": "apply_configuration",
|
|
"args": {"create_nonroot_volumes": True}
|
|
},
|
|
{
|
|
"interface": "vendor",
|
|
"step": "send_raw",
|
|
"args": {"raw_bytes": "0x00 0x00 0x00 0x00"}
|
|
}]
|
|
}
|
|
|
|
In the above example, the node's RAID interface would apply the set RAID
|
|
configuration, and then the vendor interface's ``send_raw`` step would be
|
|
called to send a raw command to the BMC. Please note, ``send_raw`` is only
|
|
available for the ``ipmi`` hardware type.
|
|
|
|
Alternatively, you can specify a runbook instead of service_steps::
|
|
|
|
{
|
|
"target":"service",
|
|
"runbook": "<runbook_name_or_uuid>"
|
|
}
|
|
|
|
The specified runbook must match one of the node's traits to be used.
|
|
|
|
Starting servicing via "openstack baremetal" CLI
|
|
------------------------------------------------
|
|
|
|
Servicing is available via the ``baremetal node service`` command,
|
|
starting with Bare Metal API version 1.87.
|
|
|
|
The argument ``--service-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 service steps.
|
|
Using '-' to signify stdin is common in Unix utilities.
|
|
|
|
Examples of doing this with a JSON string::
|
|
|
|
baremetal node service <node> \
|
|
--service-steps '[{"interface": "deploy", "step": "example_task"}]'
|
|
|
|
Or with a file::
|
|
|
|
baremetal node service <node> \
|
|
--service-steps my-service-steps.txt
|
|
|
|
Or with stdin::
|
|
|
|
cat my-clean-steps.txt | baremetal node service <node> \
|
|
--service-steps -
|
|
|
|
To use a runbook instead of specifying service steps:
|
|
|
|
baremetal node service <node> --runbook <runbook_name_or_uuid>
|
|
|
|
Using Runbooks for Servicing
|
|
----------------------------
|
|
Similar to manual cleaning, you can use runbooks for node servicing.
|
|
Runbooks provide a predefined list of service steps associated with nodes
|
|
via traits.
|
|
|
|
To use a runbook for servicing:
|
|
|
|
baremetal node service <node> --runbook <runbook_name_or_uuid>
|
|
|
|
Ensure that the runbook matches one of the node's traits before using it
|
|
for servicing.
|
|
|
|
Available Steps in Ironic
|
|
-------------------------
|
|
|
|
ipmi hardware type
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
vendor.send_raw
|
|
^^^^^^^^^^^^^^^
|
|
|
|
This step is covered in the :doc:`/admin/drivers/ipmitool` documentation
|
|
and is usable as a service step in addition to a deploy step.
|
|
|
|
redfish hardware type
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
bios.apply_configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This is covered in the :ref:`bios` configuration documentation as it
|
|
started as a cleaning step. It is a standardized cross-interface name.
|
|
|
|
management.update_firmware
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This step is covered in the :doc:`/admin/drivers/redfish` and is intended
|
|
to facilitate firmware updates via the BMC.
|
|
|
|
raid.apply_configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This step is covered in the :doc:`/admin/drivers/redfish` and is intended
|
|
to facilitate applying raid configuration.
|
|
|
|
raid.delete_configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This step is covered in the :doc:`/admin/drivers/redfish` and is intended
|
|
to delete configuration.
|
|
|
|
Agent
|
|
~~~~~
|
|
|
|
raid.apply_configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This is the standardized RAID passthrough interface for the agent, and can
|
|
be leveraged like other RAID interfaces.
|
|
|
|
|
|
Available steps in Ironic-Python-Agent
|
|
--------------------------------------
|
|
|
|
.. note::
|
|
Steps available from the agent will be populated once support has
|
|
merged in the agent to expose the steps to the ironic deployment.
|
|
|
|
Servicing Network
|
|
=================
|
|
|
|
If you are using the Neutron DHCP provider (the default) you will also need to
|
|
ensure you have configured a servicing network. This network will be used to
|
|
boot the ramdisk for in-band service operations. This setting is configured
|
|
utilizing the :oslo.config:option:`neutron.servicing_network` configuration parameter.
|