openstack/ironic
Code Issues Proposed changes

doc: Update the runbook API usage

Browse Source 
Improve documentation on how to create, associate and use runbooks
with nodes via traits for cleaning and servicing operations.

Change-Id: If99866ef8bfc200b430f17cff784cf96e916536d
This commit is contained in:
cid 2025-03-12 13:50:18 +01:00
parent 3f387f3f3d
commit da99e11548
4 changed files with 145 additions and 9 deletions

5
doc/source/admin/cleaning.rst

@ -292,10 +292,6 @@ Or with stdin::
cat my-clean-steps.txt | baremetal node clean <node> \
--clean-steps -
To use a runbook instead of specifying clean steps:
baremetal node clean <node> --runbook <runbook_name_or_uuid>
Runbooks for Manual Cleaning
----------------------------
Instead of passing a list of clean steps, operators can now use runbooks.
@ -309,6 +305,7 @@ To use a runbook for manual cleaning:
Runbooks must be created and associated with nodes beforehand. Only runbooks
that match the node's traits can be used for cleaning that node.
For more information on the runbook API usage, see :ref:`runbooks`.
Cleaning Network
================

1
doc/source/admin/features.rst

@ -27,3 +27,4 @@ Bare Metal Service Features
Deploying with Anaconda <anaconda-deploy-interface>
Node History <node-history>
OCI Container Registry Support <oci-container-registry>
Runbooks for Cleaning & Servicing <runbooks>

142
doc/source/admin/runbooks.rst Normal file

@ -0,0 +1,142 @@
.. _runbooks:
=================================
Runbooks for Cleaning & Servicing
=================================
Overview
========
The Runbook resource represents a collection of steps that define a
series of actions to be executed on a node during cleaning and servicing
operations. Runbooks enable users to perform simple and complex operations
in a consistent, predefined and automated manner.
A runbook is matched for a node if the runbook's name matches a trait in the
node. So, runbooks can be created to match already existing traits for select
nodes or the other way around; either way a valid runbook name must be unique
and follow the traits naming convention since that's the basis of association
with a node.
Hence, runbook names can be either standard or custom. Standard runbook names
are listed in the `os_traits library <https://docs.openstack.org/os-traits/latest/>`_.
Custom traits must be prefixed with ``CUSTOM_``, contain only upper case
characters A to Z, digits 0 to 9, or underscores and be no longer than 255
characters in length.
No two runbooks can have the same name, as runbook names must be unique
within the system.
Access Control for Runbooks
---------------------------
Runbooks implements a role-based access control model that determines who can
create, modify, and use them:
The ``owner`` and ``public`` fields determine a runbook's accessibility:
* If ``owner`` is non-null (``public`` is automatically false), the runbook is
scoped to that project and only usable on nodes owned or leased by that
project
* If ``owner`` is null and ``public`` is false, only system-scoped users can access
or use the runbook
* If ``owner`` is null and ``public`` is true, any project can use the runbook on
compatible nodes, but only system-scoped users can modify it
.. note::
For design details and implementation specifics, please see the
`Runbooks specification <https://specs.openstack.org/openstack/ironic-specs/specs/not-implemented/runbooks.html>`_.
Purpose of Trait Matching
-------------------------
The trait matching mechanism serves as an access control to ensure that
runbooks are only executed on pre-approved nodes.
When executing a runbook, you must explicitly specify which runbook to run.
Currently, there is no way to execute multiple runbooks on a single node with
one command. However, you can include all necessary steps in a single
comprehensive runbook if you need to perform multiple operations.
You can verify that a node has the required trait for a runbook::
baremetal node trait list <node>
Refer to the `Ironic API reference for runbooks <https://docs.openstack.org/api-ref/baremetal/#runbooks-runbooks>`_
for information on how to create, and manage runbooks.
For more details about node cleaning and servicing operations, please see
:ref:`cleaning` and :ref:`servicing`.
Example Runbook
===============
.. code-block:: bash
baremetal runbook create --name CUSTOM_FIRMWARE_UPGRADE \
--steps '[
{
"interface": "management",
"step": "reset_bios_to_default",
"args": {},
"order": 1
},
{
"interface": "management",
"step": "update_firmware",
"args": {
"firmware_url": "https://example.com/firmware.bin",
"component": "bios"
},
"order": 2
},
{
"interface": "management",
"step": "reboot",
"args": {},
"order": 3
}
]'
The output of the create command would show the complete runbook details::
+------------+---------------------------------------------------------------------------------------------------------+
| Field | Value |
+------------+---------------------------------------------------------------------------------------------------------+
| created_at | 2025-03-12T14:16:26.054115+00:00 |
| extra | {} |
| name | CUSTOM_FIRMWARE_UPGRADE |
| owner | None |
| public | False |
| steps | [{'interface': 'management', 'step': 'reset_bios_to_default', 'args': {}, 'order': 1}, {'interface': |
| | 'management', 'step': 'update_firmware', 'args': {'firmware_url': 'https://example.com/firmware.bin', |
| | 'component': 'bios'}, 'order': 2}, {'interface': 'management', 'step': 'reboot', 'args': {}, 'order': |
| | 3}] |
| updated_at | None |
| uuid | 160ff684-5216-4874-9a61-775c3a17c892 |
+------------+---------------------------------------------------------------------------------------------------------+
Cleaning and Servicing
======================
Once a runbook is created and associated with a node via matching traits,
it can be used in place of explicit cleaning or servicing steps.
For cleaning operations::
# Using a runbook name
baremetal node clean --runbook CUSTOM_FIRMWARE_UPGRADE node-0
# Or using a runbook UUID
baremetal node clean --runbook 160ff684-5216-4874-9a61-775c3a17c892 node-0
For servicing operations::
# Using a runbook name
baremetal node service --runbook CUSTOM_FIRMWARE_UPGRADE node-0
# Or using a runbook UUID
baremetal node service --runbook 160ff684-5216-4874-9a61-775c3a17c892 node-0
These commands will execute all the steps defined in the runbook in the
specified order.

6
doc/source/admin/servicing.rst

@ -146,10 +146,6 @@ 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.
@ -161,7 +157,7 @@ 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.
for servicing. For more information on the runbook API usage, see :ref:`runbooks`.
Available Steps in Ironic
-------------------------