openstack/ironic
Code Issues Proposed changes

Follow up to the runbooks change (#922142)

Browse Source 
Update api-ref, documentation to reflect the new
endpoints and the new way to set node provision state.

Related-Bug: #2027690
Change-Id: I2106691c08eb04d1001ccf97e6e08fc811356874
This commit is contained in:
cid 2024-08-07 20:23:00 +01:00
parent 8b296e242b
commit ba096e091a
14 changed files with 305 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
api-ref/source/baremetal-api-v1-node-management.inc
View File

@ -454,6 +454,12 @@ detailed documentation of the Ironic State Machine is available
A node can be serviced by setting the provision target state to ``service``
with a list of ``service_steps``.
.. versionadded:: 1.92
Added the ability to allow for predefined sets of steps to be executed
during provisioning by passing in a ``runbook_ident`` that's already
approved for the given node, as an alternative to providing ``clean_steps``
or ``service_steps`` dictionary.
Normal response code: 202
Error codes:
@ -475,6 +481,7 @@ Request
- service_steps: service_steps
- rescue_password: rescue_password
- disable_ramdisk: disable_ramdisk
- runbook: runbook_ident
**Example request to deploy a Node, using a configdrive served via local webserver:**
@ -488,6 +495,17 @@ Request
.. literalinclude:: samples/node-set-clean-state.json
**Example request to service a Node, with custom service step:**
.. literalinclude:: samples/node-set-service-state.json
**Example request to set provision state for a Node with a runbook:**
.. literalinclude:: samples/node-set-provision-state.json
.. note:: Use ``runbook`` as an alternative to ``clean_steps`` or
``service_steps``. If ``runbook`` is provided, ``clean_steps`` or
``service_steps`` must not be included in the request.
Set RAID Config
===============

4
api-ref/source/baremetal-api-v1-runbooks.inc
View File

@ -37,8 +37,8 @@ Request
- uuid: req_uuid
- extra: req_extra
Request Step
------------
Request Runbook Step
--------------------
.. rest_parameters:: parameters.yaml

1
api-ref/source/index.rst
View File

@ -29,6 +29,7 @@
.. include:: baremetal-api-v1-allocation.inc
.. include:: baremetal-api-v1-node-allocation.inc
.. include:: baremetal-api-v1-deploy-templates.inc
.. include:: baremetal-api-v1-runbooks.inc
.. include:: baremetal-api-v1-nodes-history.inc
.. include:: baremetal-api-v1-nodes-inventory.inc
.. include:: baremetal-api-v1-shards.inc

67
api-ref/source/parameters.yaml
View File

@ -116,6 +116,12 @@ portgroup_ident:
in: path
required: true
type: string
runbook_ident:
description: |
The UUID or name of the runbook.
in: path
required: true
type: string
trait:
description: |
A single trait for this node.
@ -1671,6 +1677,13 @@ req_description:
in: body
required: false
type: string
req_disable_ramdisk:
description: |
Whether to boot ramdisk while using a runbook for cleaning or servicing
operation.
in: body
required: false
type: boolean
req_driver_info:
description: |
All the metadata required by the driver to manage this Node. List of fields
@ -2024,6 +2037,60 @@ retired_reason:
in: body
required: false
type: string
runbook_name:
description: |
The unique name of the runbook. It must be prefixed with ``CUSTOM_``,
which makes it conform to the TRAITS_SCHEMA format. The runbook name must
match a node trait indicating it can run on a node.
in: body
required: true
type: string
runbook_owner:
description: |
The unique identifier of the runbook owner.
This must be ``null`` if ``runbook_public`` is ``true``.
in: body
required: false
type: string
runbook_public:
description: |
Indicates whether a runbook is available for public use or not.
This must be ``false`` if ``runbook_owner`` is not ``null``.
in: body
required: false
type: boolean
runbook_step_args:
description: |
A dictionary of arguments that are passed to the runbook step method.
in: body
required: true
type: object
runbook_step_interface:
description: |
The name of the driver interface.
in: body
required: true
type: string
runbook_step_order:
description: |
A non-negative integer order for the step.
in: body
required: true
type: integer
runbook_step_step:
description: |
The name of the runbook step method on the driver interface.
in: body
required: true
type: string
runbook_steps:
description: |
The runbook steps of the runbook template. Must be a list of dictionaries
containing at least one runbook step. See `Request Runbook Step`_ for step
parameters.
in: body
required: true
type: array
secure_boot:
description: |
Indicates whether node is currently booted with secure_boot turned on.

4
api-ref/source/samples/node-set-provision-state.json Normal file
View File

@ -0,0 +1,4 @@
{
"target": "clean",
"runbook": "runbook_ident"
}

12
api-ref/source/samples/node-set-service-state.json Normal file
View File

@ -0,0 +1,12 @@
{
"target":"service",
"sevice_steps": [
{
"interface": "raid",
"step": "apply_configuration",
"args": {
"create_nonroot_volumes": "True"
}
}
]
}

19
api-ref/source/samples/runbook-create-request.json Normal file
View File

@ -0,0 +1,19 @@
{
"extra": {},
"name": "CUSTOM_AWESOME",
"steps": [
{
"interface": "bios",
"step": "apply_configuration",
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"order": 1
}
]
}

34
api-ref/source/samples/runbook-create-response.json Normal file
View File

@ -0,0 +1,34 @@
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

39
api-ref/source/samples/runbook-detail-response.json Normal file
View File

@ -0,0 +1,39 @@
{
"runbooks": [
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"disable_ramdisk": false,
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
]
}

18
api-ref/source/samples/runbook-list-response.json Normal file
View File

@ -0,0 +1,18 @@
{
"runbooks": [
{
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
]
}

35
api-ref/source/samples/runbook-show-response.json Normal file
View File

@ -0,0 +1,35 @@
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"disable_ramdisk": false,
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

7
api-ref/source/samples/runbook-update-request.json Normal file
View File

@ -0,0 +1,7 @@
[
{
"path" : "/name",
"value" : "CUSTOM_AWESOME2",
"op" : "replace"
}
]

34
api-ref/source/samples/runbook-update-response.json Normal file
View File

@ -0,0 +1,34 @@
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME2",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": "2024-08-18T22:28:49.653974+00:00",
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}

15
doc/source/contributor/webapi-version-history.rst
View File

@ -2,6 +2,21 @@
REST API Version History
========================
1.92 (Dalmatian)
-----------------------
Adds runbooks, a predefined list of steps that can be run on
nodes associated via traits and used in place of an explicit
list of steps for manual cleaning or servicing, to enable
self-service of maintenance items by project members.
* Adds a new REST API endpoint `/v1/runbooks/` with basic CRUD support.
* Extends the `/v1/nodes/<node>/states/provision` API to accept a runbook
identifier (name or UUID) instead of `clean_steps` or `service_steps` for
servicing or manual cleaning.
* Implements RBAC-aware lifecycle management for runbooks, allowing projects
to limit who can CRUD and use a runbook.
1.91 (Dalmatian)
-----------------------