ironic — REST API

REST API — ironic — branch stable/2026.2

Branch stable/2026.2 @ 39ce09ec3b0d — repository https://opendev.org/openstack/ironic — analysed on 2026-10-29

Ironic exposes one API, /v1, served by ironic-api (or by the all-in-one ironic process). It is a Pecan application (ironic/api/app.py:80) with object dispatch: the v1 root controller maps the first path segment to a sub-controller (ironic/api/controllers/v1/__init__.py:126), and each sub-controller is a Pecan RestController whose verbs, _custom_actions, _subcontroller_map and _lookup produce the routes. There is no route table in the code, so the table below was discovered by probing the live application (_rewrite/tools/ironic_api.py, see 07 § 1): 131 operations, plus 107 (method, path) pairs that Pecan dispatches to a handler although nobody documents them ("dispatch artifacts", § 3.3).

1. Cross-cutting rules

2. Endpoint table

The Min version column is the first microversion at which the route stops being rejected as "not available in this version" (from the api_version decorator when present, otherwise from the version probe). Documented errors come from the api-ref; the observed ones are in _rewrite/observed-errors-api-tests_stable-2026.2.md. Error meanings are in 02-errors.

<!-- GEN:routes-table -->

<!-- /GEN:routes-table -->

3. Spec/code mismatches found while probing

3.1 Routes documented but not served

3.2 Unexpected 500s seen by the probe

• DELETE /v1/inspection_rules (collection, 1.96+) is documented as "delete all rules" but answers 500 "tuple index out of range" when called without an id in this configuration [inferred: the handler indexes a missing argument], ironic/api/controllers/v1/inspection_rule.py:320.
• GET …/indicators/{component}/{indicator} above.

3.3 Pecan dispatch artifacts

Pecan's RestController hands any verb on a known path to the controller's verb method: PATCH /v1/nodes reaches NodesController.patch without an identifier, GET /v1/nodes/{id}/states/power reaches NodeStatesController.get, POST /v1/ports/{id} reaches PortsController.post. They answer 400/404/405/500 depending on the handler's argument checks; their exact outcomes per microversion are in _rewrite/routes_stable-2026.2.json (dispatch_artifact: true, version_probe). A rewrite should answer 405 on them; no client in the client set relies on them (see 07 § 4).

4. Functional description by resource

4.1 Root and version discovery — GET /, GET /v1/

• Purpose: tell clients which API versions exist and where the resources are.
• Actor: anyone (public routes, no token).
• Flow: GET / returns {"name", "description", "versions": [...], "default_version": {"id": "v1", "version": "1.115", "min_version": "1.1", "status": "CURRENT", "links": [...]}} (ironic/api/controllers/root.py:39). GET /v1/ returns links to every top-level collection, adding the versioned ones only when the requested microversion allows them (ironic/api/controllers/v1/__init__.py:117).
• Clients relying on it: ironic-python-agent reads default_version.version to choose the microversion of its lookup and heartbeat calls (ipa:ironic_python_agent/ironic_api_client.py:121); python-ironicclient reads the version headers.

4.2 Nodes — /v1/nodes

• Purpose: register bare metal machines, describe how to reach their BMC (driver, driver_info), their hardware (properties), what is deployed on them (instance_info, instance_uuid), and who may use them (owner, lessee).
• Actor: system admin/member; project admins of the owner project (baremetal:node:create:self_owned_node, 1.80+, ironic/api/controllers/v1/node.py:3018); readers list and show. Nova's ironic virt driver lists and patches nodes with a service token.
• Preconditions: the driver (hardware type) must be enabled on at least one live conductor, otherwise POST answers 400 "No valid host was found" (NoValidHost turned into 400), ironic/api/controllers/v1/node.py:3092.
• Business rules:
  • name must be a valid logical name (unique, 1.5+; special characters relaxed in 1.10), ironic/api/controllers/v1/node.py:2644.
  • POST validates against the node JSON schema built from versioned fields (ironic/api/controllers/v1/node.py:250); fields not allowed in the requested version are rejected with 406.
  • provision_state is never accepted in the body: new nodes start in enroll (1.11+) or available (older versions), ironic/db/sqlalchemy/api.py:816.
  • PATCH is a JSON patch; each patched path needs its own policy (baremetal:node:update:<field>, …:update_extra, …:update_instance_info, …:set_maintenance for /maintenance since the CVE fix of this branch), ironic/api/controllers/v1/node.py:3147. Updating driver, interfaces or driver_info is refused in unstable states (states.UPDATE_ALLOWED_STATES, ironic/common/states.py:246).
  • DELETE only in manageable, enroll or adopt failed (ironic/common/states.py:251) and only when no instance is associated and the node is not protected.
• Flow:
  1. (synchronous, API) policy check, schema validation, name/UUID resolution.
  2. (synchronous, RPC call) create_node / update_node / destroy_node to the conductor chosen by the hash ring for (conductor_group, driver) (ironic/conductor/rpcapi.py:247); the conductor validates the driver interfaces and writes the row.
  3. Response 201 (create, with Location), 200 (patch) or 204 (delete).
• Outcome: the node exists in enroll with power_state: null; the periodic power sync fills power_state (see 05 § _sync_power_states).
• Effects visible elsewhere: versioned notifications baremetal.node.create|update|delete.{start,end,error}; Nova's resource tracker sees the node on its next poll.
• Limitations: no conductor alive → 503 "Resource temporarily unavailable" on every write (TemporaryFailure, ironic/conductor/rpcapi.py:278); a node locked by an operation → 409 NodeLocked after [conductor]/node_locked_retry_attempts retries.

4.3 Node provision state — PUT /v1/nodes/{node_ident}/states/provision

• Purpose: drive the node through its lifecycle: manage, provide, inspect, clean, active/deploy, rebuild, deleted/undeploy, rescue, unrescue, adopt, abort, unhold, service.
• Actor: policy baremetal:node:set_provision_state (system member, owner member, lessee admin); clean_steps and service_steps need extra policies; per-step policies baremetal:step:execute:<interface>.<step> apply when defined (ironic/conductor/steps.py:753).
• Preconditions and rules, in this order (ironic/api/controllers/v1/node.py:1148):
  1. Node policy and retrieval (404 for a foreign project).
  2. The verb must exist in the requested microversion (check_allow_management_verbs, ironic/api/controllers/v1/utils.py:935): manage/provide 1.4, inspect 1.6, abort 1.13, clean 1.15, adopt 1.17, rescue 1.38, deploy/undeploy 1.73, unhold 1.85, service 1.87; otherwise 406.
  3. active/rebuild refused in maintenance (400 NodeInMaintenance, ironic/api/controllers/v1/node.py:1274).
  4. The transition must be actionable from the current state in the state machine (ironic/api/controllers/v1/node.py:1282); if not, **409 NodeLocked** when the node is reserved, else **400 InvalidStateRequested**.
  5. configdrive only with active/rebuild (dict form 1.56+, vendor_data 1.59+), ironic/api/controllers/v1/node.py:1298.
  6. runbook (1.92+) replaces clean_steps/service_steps; since 1.112 the node must share a trait with the runbook (ironic/api/controllers/v1/node.py:1007).
• Flow: one RPC per verb (ironic/api/controllers/v1/node.py:1073): do_node_deploy (active/rebuild/deploy), do_node_tear_down (deleted/undeploy), inspect_hardware, do_node_clean, do_node_service, do_node_rescue, do_node_unrescue, and do_provisioning_action for manage, provide, adopt, abort, unhold (ironic/conductor/manager.py:1458). All are RPC calls: the conductor takes the node lock, applies the state machine event, saves the node and spawns a worker for the long part, then returns.
• Outcome: 202 with Location: /v1/nodes/<id>/states; the node is already in the transient state (deploying, cleaning, inspecting…) with target_provision_state set. The client polls GET /v1/nodes/{id} until a stable state or a *failed state.
• Limitations: the API-side state check races with the conductor (comment in ironic/api/controllers/v1/node.py:1073): a conductor-side refusal still answers 400 InvalidStateRequested through the RPC error.

4.4 Power, boot mode, secure boot, RAID, console

4.5 Node management, traits, VIFs, virtual media, history, inventory

4.6 Ports and port groups — /v1/ports, /v1/portgroups, /v1/nodes/{id}/ports, /v1/portgroups/{id}/ports

• Purpose: record the node's NICs (MAC address, pxe_enabled, local_link_connection = switch id/port, physical_network) used for PXE/DHCP and to bind Neutron ports to the right switch port.
• Rules: MAC unique (409 MACAlreadyExists); physical_network 1.34+; is_smartnic 1.53+; name 1.88+; description 1.97+; vendor 1.100+, category 1.101+; port groups 1.23+ (mode, properties 1.26+, physical_network 1.102+, dynamic port groups 1.111+). Creating and updating ports goes through the conductor (create_port, update_port) because a port attached to a VIF of an active node cannot be changed freely.
• Effects: none on Neutron until a VIF is attached (see § 4.5 and 03 § Neutron).

4.7 Allocations — /v1/allocations, /v1/nodes/{id}/allocation

• Purpose: let a client (Metal3-like tooling, standalone use) ask Ironic to pick a free node matching a resource class, traits and candidate list, instead of choosing itself. Nova does not use allocations; it schedules through Placement.
• Flow: POST (1.52+) creates the allocation in allocating and casts nothing: the API calls create_allocation on a random conductor, which spawns do_allocate (ironic/conductor/allocations.py:34): filter available, not-maintenance, unreserved nodes with the resource class (ironic/conductor/allocations.py:103), keep those whose traits are a superset, shuffle (ironic/conductor/allocations.py:141), try to reserve them one by one and set instance_uuid/allocation_id. Final state active (node chosen) or error with last_error. Backfill (1.58+) attaches an existing deployment's node.
• Owner: 1.60+; project-scoped creators get their project as owner and only see nodes they own or lease.
• Lifecycle: see § 5.3.

4.8 Deploy templates and runbooks — /v1/deploy_templates (1.55+), /v1/runbooks (1.92+)

• Deploy templates: named lists of deploy steps; a template whose name matches one of the instance traits (instance_info.traits, set by Nova from the flavor) adds its steps to the deployment (ironic/conductor/steps.py:383). Name must be a valid trait name (CUSTOM_*).
• Runbooks: named lists of clean/service steps that a project may run on its nodes; owner/public (PATCH …/owner, …/public), traits (1.112+) select which nodes may use them; steps validated against per-step policies at creation (ironic/conductor/steps.py:791).

4.9 Other resources

4.10 Ramdisk API used by ironic-python-agent

These three endpoints are public (no Keystone token): the ramdisk has no credentials. They are protected by [api]/enable_ramdisk_endpoints, by the provision state of the node and by the agent token.

GET /v1/lookup?addresses=<mac,...>&node_uuid=<uuid> (1.22+)

• Purpose: the agent, just booted, finds which node it is running on and gets its configuration and secret token.
• Rules (ironic/api/controllers/v1/ramdisk.py:143): MACs are normalised, invalid ones ignored; neither MAC nor UUID → 400 IncompleteLookup; node not found → 404 (no detail on purpose); with [api]/restrict_lookup (default true) the node must be in LOOKUP_ALLOWED_STATES (or FASTTRACK_LOOKUP_ALLOWED_STATES with fast track), ironic/common/states.py:272.
• Flow: from 1.62 the API calls get_node_with_token on the node's conductor (ironic/conductor/manager.py:4013), which generates the token once (ironic/conductor/utils.py:1509); a second lookup gets "******" instead of the token.
• Response: {"node": {"uuid", "properties", "instance_info", "driver_internal_info"}, "config": {"heartbeat_timeout", "agent_token", "agent_token_required": true, "metrics"…, "permitted_image_formats", "tls_min_version"…}} (ironic/api/controllers/v1/ramdisk.py:46).

POST /v1/heartbeat/{node_ident} (1.22+), body {"callback_url", "agent_token", "agent_version", "agent_verify_ca", "agent_status", "agent_status_message"}

• Purpose: the agent says "I am alive at this URL"; each heartbeat is also the trigger that moves deployments, cleaning, rescue and servicing forward.
• Rules (ironic/api/controllers/v1/ramdisk.py:215): agent_version needs 1.36, agent_token 1.62, agent_verify_ca 1.68, agent_status* 1.72; callback_url must be http(s) and must not change once recorded (400 "Detected change in ramdisk provided callback_url"); missing token → 400.
• Flow: RPC call heartbeat (ironic/conductor/manager.py:3554): token check (ironic/conductor/utils.py:1543), TLS requirement ([agent]/require_tls), early 409 when the node is locked and no agent_url is known yet, then a spawned worker runs the deploy interface's heartbeat (05 § heartbeat).
• Response: 202 with no body. IPA treats 409 as "retry soon" and any other non-202 as an error.

POST /v1/continue_inspection[?node_uuid=] (1.84+; node_uuid 1.88+ with node+config response)

• Purpose: the agent posts the hardware inventory collected during inspection (replaces ironic-inspector's /v1/continue).
• Rules (ironic/api/controllers/v1/ramdisk.py:402): body must contain inventory.interfaces[].mac_address; lookup by MACs and BMC addresses (ironic/drivers/modules/inspect_utils.py); unknown node and [auto_discovery]/enabled → enrol a new node (ironic/api/controllers/v1/ramdisk.py:360).
• Flow: RPC call continue_inspection → hooks, inspection rules, storage of inventory (05).
• Response: 202 {"uuid"} before 1.88; node + config (with a new token) since.

5. Lifecycles

5.1 Node provision state

Every state, event and transition of ironic/common/state_machine.py, generated from the live state machine. The formal specification (tables, vectors) is in 07 § 3.

<!-- GEN:sm-mermaid -->

stateDiagram-v2
  state "wait call-back" as wait_call_back
  state "deploy failed" as deploy_failed
  state "deploy hold" as deploy_hold
  state "clean wait" as clean_wait
  state "clean failed" as clean_failed
  state "clean hold" as clean_hold
  state "inspect failed" as inspect_failed
  state "inspect wait" as inspect_wait
  state "adopt failed" as adopt_failed
  state "rescue wait" as rescue_wait
  state "rescue failed" as rescue_failed
  state "unrescue failed" as unrescue_failed
  state "service wait" as service_wait
  state "service failed" as service_failed
  state "service hold" as service_hold
  [*] --> enroll: POST /v1/nodes (API)
  active --> deleting: delete
  active --> deploying: rebuild
  active --> rescuing: rescue
  active --> servicing: service
  adopt_failed --> adopting: adopt
  adopt_failed --> manageable: manage
  adopting --> active: done
  adopting --> adopt_failed: fail
  available --> deploying: deploy
  available --> manageable: manage
  clean_failed --> manageable: manage
  clean_hold --> clean_failed: abort
  clean_hold --> clean_wait: unhold
  clean_wait --> clean_failed: abort
  clean_wait --> clean_failed: fail
  clean_wait --> clean_hold: hold
  clean_wait --> cleaning: resume
  cleaning --> available: done
  cleaning --> clean_failed: fail
  cleaning --> clean_hold: hold
  cleaning --> manageable: manage
  cleaning --> clean_wait: wait
  deleting --> cleaning: clean
  deleting --> error: fail
  deploy_failed --> deleting: delete
  deploy_failed --> deploying: deploy
  deploy_failed --> deploying: rebuild
  deploy_hold --> deploy_failed: abort
  deploy_hold --> wait_call_back: unhold
  deploying --> active: done
  deploying --> deploy_failed: fail
  deploying --> deploy_hold: hold
  deploying --> wait_call_back: wait
  enroll --> verifying: manage
  error --> deleting: delete
  error --> deploying: rebuild
  inspect_failed --> inspecting: inspect
  inspect_failed --> manageable: manage
  inspect_wait --> inspect_failed: abort
  inspect_wait --> manageable: done
  inspect_wait --> inspect_failed: fail
  inspect_wait --> inspecting: resume
  inspecting --> manageable: done
  inspecting --> inspect_failed: fail
  inspecting --> inspect_wait: wait
  manageable --> adopting: adopt
  manageable --> cleaning: clean
  manageable --> inspecting: inspect
  manageable --> cleaning: provide
  rescue --> deleting: delete
  rescue --> rescuing: rescue
  rescue --> unrescuing: unrescue
  rescue_failed --> deleting: delete
  rescue_failed --> rescuing: rescue
  rescue_failed --> unrescuing: unrescue
  rescue_wait --> rescue_failed: abort
  rescue_wait --> deleting: delete
  rescue_wait --> rescue_failed: fail
  rescue_wait --> rescuing: resume
  rescuing --> rescue: done
  rescuing --> rescue_failed: fail
  rescuing --> rescue_wait: wait
  service_failed --> active: abort
  service_failed --> deleting: delete
  service_failed --> service_hold: hold
  service_failed --> rescuing: rescue
  service_failed --> servicing: service
  service_failed --> service_wait: wait
  service_hold --> service_failed: abort
  service_hold --> service_failed: fail
  service_hold --> servicing: service
  service_hold --> service_wait: unhold
  service_wait --> service_failed: abort
  service_wait --> deleting: delete
  service_wait --> service_failed: fail
  service_wait --> service_hold: hold
  service_wait --> servicing: resume
  servicing --> active: done
  servicing --> service_failed: fail
  servicing --> service_hold: hold
  servicing --> service_wait: wait
  unrescue_failed --> deleting: delete
  unrescue_failed --> rescuing: rescue
  unrescue_failed --> unrescuing: unrescue
  unrescuing --> active: done
  unrescuing --> unrescue_failed: fail
  verifying --> manageable: done
  verifying --> enroll: fail
  wait_call_back --> deploy_failed: abort
  wait_call_back --> deleting: delete
  wait_call_back --> deploy_failed: fail
  wait_call_back --> deploy_hold: hold
  wait_call_back --> deploying: resume

<!-- /GEN:sm-mermaid -->

What triggers the events:

5.2 Power state

power_state ∈ {power on, power off, null}; target_power_state is set while a change is running (rebooting, soft power off, soft rebooting are only targets). Changes come from the API (change_node_power_state), from steps and deployments (ironic/conductor/utils.py:286), and from the periodic sync, which either forces the hardware back to the recorded state ([conductor]/force_power_state_during_sync, default true) or records the observed one and notifies Nova (ironic/conductor/manager.py:4574). After [conductor]/power_state_sync_max_retries failures the node goes to maintenance with fault power failure.

5.3 Allocation

stateDiagram-v2
  [*] --> allocating: POST /v1/allocations (API) / create_allocation (RPC call)
  allocating --> active: do_allocate reserved a node (conductor worker)
  allocating --> error: no suitable node / reservation failed
  allocating --> active: backfill (node given)
  active --> [*]: DELETE /v1/allocations/{id} or node deletion
  error --> [*]: DELETE
  allocating --> allocating: _check_orphan_allocations takes over a dead conductor's allocation (periodic)

Source: reverse-spec-ironic/01-rest-api_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.