From ba096e091ae11b53a7213aad3130f70780f887e0 Mon Sep 17 00:00:00 2001 From: cid Date: Wed, 7 Aug 2024 20:23:00 +0100 Subject: [PATCH] Follow up to the runbooks change (#922142) Update api-ref, documentation to reflect the new endpoints and the new way to set node provision state. Related-Bug: #2027690 Change-Id: I2106691c08eb04d1001ccf97e6e08fc811356874 --- .../baremetal-api-v1-node-management.inc | 18 +++++ api-ref/source/baremetal-api-v1-runbooks.inc | 4 +- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 67 +++++++++++++++++++ .../samples/node-set-provision-state.json | 4 ++ .../samples/node-set-service-state.json | 12 ++++ .../samples/runbook-create-request.json | 19 ++++++ .../samples/runbook-create-response.json | 34 ++++++++++ .../samples/runbook-detail-response.json | 39 +++++++++++ .../source/samples/runbook-list-response.json | 18 +++++ .../source/samples/runbook-show-response.json | 35 ++++++++++ .../samples/runbook-update-request.json | 7 ++ .../samples/runbook-update-response.json | 34 ++++++++++ .../contributor/webapi-version-history.rst | 15 +++++ 14 files changed, 305 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/samples/node-set-provision-state.json create mode 100644 api-ref/source/samples/node-set-service-state.json create mode 100644 api-ref/source/samples/runbook-create-request.json create mode 100644 api-ref/source/samples/runbook-create-response.json create mode 100644 api-ref/source/samples/runbook-detail-response.json create mode 100644 api-ref/source/samples/runbook-list-response.json create mode 100644 api-ref/source/samples/runbook-show-response.json create mode 100644 api-ref/source/samples/runbook-update-request.json create mode 100644 api-ref/source/samples/runbook-update-response.json diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc index 176432ea75..d3b485324a 100644 --- a/api-ref/source/baremetal-api-v1-node-management.inc +++ b/api-ref/source/baremetal-api-v1-node-management.inc @@ -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 =============== diff --git a/api-ref/source/baremetal-api-v1-runbooks.inc b/api-ref/source/baremetal-api-v1-runbooks.inc index 5e4392c4ab..1098739d23 100644 --- a/api-ref/source/baremetal-api-v1-runbooks.inc +++ b/api-ref/source/baremetal-api-v1-runbooks.inc @@ -37,8 +37,8 @@ Request - uuid: req_uuid - extra: req_extra -Request Step ------------- +Request Runbook Step +-------------------- .. rest_parameters:: parameters.yaml diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index ebdbb586a9..b153fe6a8a 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 0104be583d..e800631913 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -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. diff --git a/api-ref/source/samples/node-set-provision-state.json b/api-ref/source/samples/node-set-provision-state.json new file mode 100644 index 0000000000..d551b6805d --- /dev/null +++ b/api-ref/source/samples/node-set-provision-state.json @@ -0,0 +1,4 @@ +{ + "target": "clean", + "runbook": "runbook_ident" +} diff --git a/api-ref/source/samples/node-set-service-state.json b/api-ref/source/samples/node-set-service-state.json new file mode 100644 index 0000000000..6814507ec2 --- /dev/null +++ b/api-ref/source/samples/node-set-service-state.json @@ -0,0 +1,12 @@ +{ + "target":"service", + "sevice_steps": [ + { + "interface": "raid", + "step": "apply_configuration", + "args": { + "create_nonroot_volumes": "True" + } + } + ] +} diff --git a/api-ref/source/samples/runbook-create-request.json b/api-ref/source/samples/runbook-create-request.json new file mode 100644 index 0000000000..6defda1662 --- /dev/null +++ b/api-ref/source/samples/runbook-create-request.json @@ -0,0 +1,19 @@ +{ + "extra": {}, + "name": "CUSTOM_AWESOME", + "steps": [ + { + "interface": "bios", + "step": "apply_configuration", + "args": { + "settings": [ + { + "name": "LogicalProc", + "value": "Enabled" + } + ] + }, + "order": 1 + } + ] +} diff --git a/api-ref/source/samples/runbook-create-response.json b/api-ref/source/samples/runbook-create-response.json new file mode 100644 index 0000000000..97c4fe4036 --- /dev/null +++ b/api-ref/source/samples/runbook-create-response.json @@ -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" +} diff --git a/api-ref/source/samples/runbook-detail-response.json b/api-ref/source/samples/runbook-detail-response.json new file mode 100644 index 0000000000..810631c95b --- /dev/null +++ b/api-ref/source/samples/runbook-detail-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/samples/runbook-list-response.json b/api-ref/source/samples/runbook-list-response.json new file mode 100644 index 0000000000..e6a101e3ce --- /dev/null +++ b/api-ref/source/samples/runbook-list-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/samples/runbook-show-response.json b/api-ref/source/samples/runbook-show-response.json new file mode 100644 index 0000000000..919733fcbf --- /dev/null +++ b/api-ref/source/samples/runbook-show-response.json @@ -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" +} diff --git a/api-ref/source/samples/runbook-update-request.json b/api-ref/source/samples/runbook-update-request.json new file mode 100644 index 0000000000..92bb0c2ca8 --- /dev/null +++ b/api-ref/source/samples/runbook-update-request.json @@ -0,0 +1,7 @@ +[ + { + "path" : "/name", + "value" : "CUSTOM_AWESOME2", + "op" : "replace" + } +] diff --git a/api-ref/source/samples/runbook-update-response.json b/api-ref/source/samples/runbook-update-response.json new file mode 100644 index 0000000000..f786fdac7d --- /dev/null +++ b/api-ref/source/samples/runbook-update-response.json @@ -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" +} diff --git a/doc/source/contributor/webapi-version-history.rst b/doc/source/contributor/webapi-version-history.rst index fd495276e4..2f1097d373 100644 --- a/doc/source/contributor/webapi-version-history.rst +++ b/doc/source/contributor/webapi-version-history.rst @@ -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//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) -----------------------