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

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
 ===============

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
 

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

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.

api-ref/source/samples/node-set-provision-state.json

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

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"
+            }
+        }
+    ]
+}

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
+        }
+    ]
+}

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"
+}

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"
+    }
+  ]
+}

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"
+    }
+  ]
+}

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"
+}

api-ref/source/samples/runbook-update-request.json

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

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"
+}

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/<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)
 -----------------------