feat(ironic): Adds ironic runbook for performing BMC maintenances.

Author: nicholaskuechler

components/ironic/runbook-crd/README.md

@@ -90,6 +90,52 @@ spec:
 | `runbook_disk_cleaning.yaml` | Node Reuse | Secure disk erasure |
 | `runbook_gpu_node_setup.yaml` | ML/AI | GPU node configuration |
 
+## Running a Runbook
+
+Once the operator syncs the CRD into Ironic, you execute a runbook by
+transitioning a node into the `clean` provisioning state with the runbook
+specified. The node must be in `manageable` state before you can trigger
+cleaning.
+
+### OpenStack CLI
+
+```bash
+# Run a runbook by name
+openstack baremetal node clean <node-uuid> --runbook CUSTOM_BMC_MAINTENANCE
+
+# Check node state while cleaning runs
+openstack baremetal node show <node-uuid> -f value -c provision_state
+```
+
+### Python SDK
+
+```python
+from understack_workflows.ironic_node import transition
+
+# node must already be in manageable state
+transition(
+    node,
+    "clean",
+    expected_state="manageable",
+    runbook=runbook_uuid,
+)
+```
+
+The `transition` helper calls `set_node_provision_state` and waits for the
+node to return to `manageable` once all steps complete.
+
+### Trait-Based Automatic Execution
+
+Runbooks can also be triggered automatically by matching node traits. Add the
+runbook name as a trait on the node:
+
+```bash
+openstack baremetal node add trait <node-uuid> CUSTOM_BMC_MAINTENANCE
+```
+
+Workflow code (e.g. `apply_firmware_updates` in `ironic_node.py`) can then
+discover matching traits and execute the corresponding runbooks in order.
+
 ## Support
 
 - **Ironic Documentation**: https://docs.openstack.org/ironic/latest/

components/ironic/runbook-crd/kustomization.yaml

@@ -7,3 +7,4 @@ namespace: openstack
 # Create namespace if it doesn't exist
 resources:
   - bases/baremetal.ironicproject.org_runbooks.yaml
+  - runbooks/runbook_bmc_maintenance.yaml

components/ironic/runbook-crd/runbooks/runbook_bmc_maintenance.yaml

@@ -0,0 +1,16 @@
+apiVersion: baremetal.ironicproject.org/v1alpha1
+kind: IronicRunbook
+metadata:
+  name: bmc-maintenance
+  namespace: openstack
+spec:
+  runbookName: CUSTOM_BMC_MAINTENANCE
+
+  steps:
+    - interface: management
+      step: clear_job_queue
+      order: 1
+
+    - interface: management
+      step: set_bmc_clock
+      order: 2

components/ironic/values.yaml

@@ -103,7 +103,7 @@ conf:
       keep_ports: "present"
     redfish:
       # Redfish inspection hooks run after inspecting out-of-band using the BMC:
-      inspection_hooks: "validate-interfaces,ports,port-bios-name,architecture,pci-devices,resource-class"
+      inspection_hooks: "validate-interfaces,ports,port-bios-name,architecture,pci-devices,resource-class,bmc-maintenance"
       # To avoid SSL issues due to the system clock differing, have the conductor
       # set the system clock to its time whenever we go to boot the machine into
       # IPA

python/ironic-understack/ironic_understack/inspect_hook_bmc_maintenance.py

@@ -0,0 +1,32 @@
+from ironic import objects
+from ironic.drivers.modules.inspector.hooks import base
+from oslo_log import log as logging
+
+LOG = logging.getLogger(__name__)
+
+BMC_MAINTENANCE_TRAIT = "CUSTOM_BMC_MAINTENANCE"
+
+
+class InspectHookBmcMaintenance(base.InspectionHook):
+    """Ensure all nodes have the CUSTOM_BMC_MAINTENANCE trait.
+
+    This trait authorizes the BMC maintenance runbook to be executed on the
+    node.  The runbook clears the BMC job queue and synchronizes the BMC clock.
+    """
+
+    def __call__(self, task, inventory, _plugin_data):
+        node = task.node
+        existing_traits = set(node.traits.get_trait_names())
+
+        if BMC_MAINTENANCE_TRAIT in existing_traits:
+            LOG.debug("Node %s already has trait %s", node.uuid, BMC_MAINTENANCE_TRAIT)
+            return
+
+        required_traits = existing_traits | {BMC_MAINTENANCE_TRAIT}
+        LOG.info(
+            "Adding trait %s to node %s",
+            BMC_MAINTENANCE_TRAIT,
+            node.uuid,
+        )
+        objects.TraitList.create(task.context, task.node.id, required_traits)
+        node.save()

python/ironic-understack/pyproject.toml

@@ -25,6 +25,7 @@ update-baremetal-port = "ironic_understack.inspect_hook_update_baremetal_ports:I
 port-bios-name = "ironic_understack.port_bios_name_hook:PortBiosNameHook"
 node-name-check = "ironic_understack.inspect_hook_node_name_check:InspectHookNodeNameCheck"
 chassis_model = "ironic_understack.inspect_hook_chassis_model:InspectHookChassisModel"
+bmc-maintenance = "ironic_understack.inspect_hook_bmc_maintenance:InspectHookBmcMaintenance"
 
 [project.entry-points."ironic.hardware.interfaces.inspect"]
 redfish-understack = "ironic_understack.redfish_inspect_understack:UnderstackRedfishInspect"