ironic — Interactions

Interactions — ironic — branch stable/2026.2

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

Ironic talks to five kinds of systems: its database, its RPC transport between API and conductors, other OpenStack services over REST, the ramdisk agent (ironic-python-agent, IPA) over HTTP, and the hardware itself (BMCs over Redfish or IPMI, the provisioning network over DHCP/TFTP/HTTP). The last two have no equivalent in the other OpenKeel services and drive most of the Kubernetes design of openkeel-ironic (07 § 9).

flowchart LR
  subgraph clients
    nova[nova-compute ironic driver]
    cli[openstack baremetal / SDK]
  end
  api[ironic-api] -->|SQL| db[(MariaDB)]
  cond[ironic-conductor] -->|SQL| db
  api -->|RPC call/cast: oslo.messaging or JSON-RPC| cond
  nova -->|REST /v1 + token| api
  cli -->|REST /v1| api
  ipa[IPA in ramdisk] -->|REST lookup / heartbeat / continue_inspection| api
  cond -->|REST :9999 /v1/commands| ipa
  cond -->|Redfish HTTPS / IPMI UDP 623| bmc[(BMC)]
  cond -->|REST| glance[Glance] & swift[Swift] & neutron[Neutron] & cinder[Cinder]
  cond -->|REST os-server-external-events| novaapi[Nova API]
  cond -->|DHCP options via Neutron or dnsmasq files| dhcp[(DHCP/TFTP)]
  cond -->|files under http_root| http[(HTTP server)]
  net[ironic-networking] -->|switch drivers| sw[(switches)]
  cond -->|RPC| net

1. RPC between API and conductors

1.1 Transports

JSON-RPC is present on this branch and is the natural choice for OpenKeel (no broker, one Service per conductor pod, see 07 § 9.2). Since RPC 1.58 a conductor using JSON-RPC registers itself as host:port (ironic/conductor/base_manager.py:115), so the hash ring entries are directly the JSON-RPC endpoints.

1.2 Routing (hash ring)

• One ring per "<conductor_group>:<hardware_type>" built from the conductors table rows that are online (ironic/db/sqlalchemy/api.py:1573) with tooz.hashring.HashRing(hosts, partitions=2**[DEFAULT]/hash_partition_exponent, hash_function=[DEFAULT]/hash_ring_algorithm) — 32 partitions, md5 by default (ironic/common/hash_ring.py:68).
• A node is sent to ring.get_nodes(node.uuid) (ironic/conductor/rpcapi.py:247). Rings are cached [DEFAULT]/hash_ring_reset_interval seconds (15) and rebuilt when the driver/group is missing.
• Requests not tied to a node (driver properties, create allocation) go to a random live conductor (ironic/conductor/rpcapi.py:278, ironic/conductor/rpcapi.py:288).
• Vectors (_rewrite/hash-ring-vectors_stable-2026.2.json) let a rewrite check it maps nodes exactly like Ironic; this matters only during a mixed Python/Go migration (a Go-only deployment just needs a consistent rule).

1.3 RPC methods (conductor API version 1.62)

All are call except continue_node_clean, continue_node_deploy, continue_node_service (cast). Arguments are serialised versioned objects (IronicObjectSerializer); results are objects or plain JSON.

<!-- GEN:rpc-table -->

Networking service (ironic-networking, topic ironic.networking_manager):

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

1.4 Sample frames

oslo.messaging call (do_node_deploy), AMQP body on exchange ironic, routing key ironic.conductor_manager.<host>:

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"do_node_deploy\", \"args\": {\"node_id\": \"1be26c0b-03f2-4d2e-ae87-c02d7f33c123\", \"rebuild\": false, \"configdrive\": null, \"deploy_steps\": null}, \"version\": \"1.52\", \"namespace\": null, \"_msg_id\": \"6b2…\", \"_reply_q\": \"reply_7f3…\", \"_unique_id\": \"a1c…\", \"_context_request_id\": \"req-…\", \"_context_project_id\": \"…\", \"_context_roles\": [\"admin\"], \"_context_system_scope\": \"all\"}"}

JSON-RPC (same call) — POST http://ironic-conductor-0.ironic-conductor:8089/ (ironic/common/json_rpc/client.py:218):

{"jsonrpc": "2.0", "method": "do_node_deploy", "id": "req-…",
 "params": {"context": {"user_id": "…", "project_id": "…", "roles": ["admin"], "request_id": "req-…", "system_scope": "all"},
            "node_id": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rebuild": false, "configdrive": null,
            "deploy_steps": null, "rpc.version": "1.52"}}

Reply {"jsonrpc": "2.0", "result": null, "id": "req-…"}; error {"jsonrpc": "2.0", "id": "req-…", "error": {"code": 409, "message": "Node … is locked by host …", "data": {"class": "ironic.common.exception.NodeLocked"}}} (ironic/common/json_rpc/server.py:163). A cast has no id and gets 204.

1.5 Networking service RPC

ironic-networking (new process, ironic/command/networking.py:39) listens on topic ironic.networking_manager (ironic/common/rpc.py:37) and drives physical switches through switch drivers (generic-switch wraps networking-generic-switch, noop), for the ironic-networking network interface. Its five calls (update_port, reset_port, get_switches, update_lag, delete_lag) are in the table above. It needs switch credentials in a config file (ironic/networking/manager.py:111).

2. Notifications

Versioned notifications on [oslo_messaging_notifications] (driver noop by default): baremetal.<object>.<action>.<status> with object ∈ node, port, portgroup, chassis, volume connector/target, deploy template, allocation, runbook, and statuses start/end/success/error (ironic/conductor/notification_utils.py:65). Provision transitions emit baremetal.node.provision_set.{start,end,success,error} computed from stable/unstable states (ironic/conductor/task_manager.py:508); power changes baremetal.node.power_set.* and power_state_corrected.success. Sensor data (hardware.ipmi.metrics) is sent when [sensor_data]/send_sensor_data (ironic/common/rpc.py:142). Nobody in the OpenKeel client set consumes them; Ceilometer-style consumers would.

3. Database

21 tables (ironic/db/sqlalchemy/models.py); the migrated schema equals the models except one index name (_rewrite/schema-diff_stable-2026.2.md).

Notable transactions

• Node lock — UPDATE nodes SET reservation=:host WHERE id=:id AND reservation IS NULL; rowcount != 1 → NodeLocked (ironic/db/sqlalchemy/api.py:752); release UPDATE … SET reservation=NULL WHERE id=:id AND reservation=:host (ironic/db/sqlalchemy/api.py:793). Retried by TaskManager (ironic/conductor/task_manager.py:343). This is the only concurrency control on nodes: there is no optimistic version column.
• Conductor heartbeat — UPDATE conductors SET updated_at=now(), online=:online WHERE hostname=:host every 10 s (ironic/db/sqlalchemy/api.py:1524); a conductor is offline when updated_at is older than [conductor]/heartbeat_timeout (60 s), ironic/db/sqlalchemy/api.py:1596.
• Startup — clear_node_reservations_for_conductor releases locks held under this hostname by a previous run (ironic/db/sqlalchemy/api.py:1538); then stuck transient states are failed (05).
• Allocation takeover — UPDATE allocations SET conductor_affinity=:new WHERE id=:id AND conductor_affinity=:old (ironic/db/sqlalchemy/api.py:2584).
• Lookup by MAC — join ports → nodes on address IN (...); more than one node → 404 (ironic/db/sqlalchemy/api.py:1736).

4. Outbound REST calls

5. The ramdisk agent (ironic-python-agent)

Two directions, both HTTP(S) on the provisioning network:

Commands sent by the conductor (ironic/drivers/modules/agent_client.py): image.install_bootloader, clean.get_clean_steps, clean.execute_clean_step, deploy.get_deploy_steps, deploy.execute_deploy_step (the write_image step), service.get_service_steps, service.execute_service_step, standby.get_partition_uuids, standby.power_off, standby.reboot, standby.sync, log.collect_system_logs, rescue.finalize_rescue, system.lockdown. The agent serves them at ipa:ironic_python_agent/api/app.py:140.

Timeouts and retries: each POST times out after [agent]/command_timeout (60 s); connection errors are retried [agent]/max_command_attempts times (3); a polled command is checked every command_wait_interval (6 s) up to command_wait_attempts (100). On timeout the conductor asks the agent for the status of the last command before declaring failure (ironic/drivers/modules/agent_client.py:420). TLS: IPA can generate a certificate and send it as agent_verify_ca in the heartbeat (auto-TLS); [agent]/require_tls (default true) makes the conductor reject plain-HTTP callback_urls (ironic/conductor/manager.py:3554).

Sample command:

POST https://10.10.0.23:9999/v1/commands/?wait=false&agent_token=4LpX…  HTTP/1.1
Content-Type: application/json

{"name": "deploy.execute_deploy_step",
 "params": {"step": {"interface": "deploy", "step": "write_image", "args": {"image_info": {"id": "…", "urls": ["http://10.10.0.2:8080/images/…"], "disk_format": "raw", "checksum": "…"}, "configdrive": "…"}, "priority": 80},
            "node": {…}, "ports": [{…}], "deploy_version": "…"}}

Answer: {"id": "…", "command_name": "execute_deploy_step", "command_status": "RUNNING", "command_result": null, "command_error": null}; later GET /v1/commands/ shows SUCCEEDED or FAILED with command_error.

6. Hardware: BMCs and the provisioning network

7. Other local effects

• Files: per-node PXE/iPXE configs, ISO images, image cache (master images + per-node hard links), configdrive temporary files, IPA log tarballs ([agent]/deploy_logs_local_path).
• Processes: ipmitool, socat (serial console proxy), qemu-img (image conversion), mkisofs/xorriso (ISO), container runtimes for graphical consoles (ironic/console/container/*).
• Privileges: none via privsep for the shipped interfaces; the conductor needs write access to tftp_root/http_root and network reachability of the BMCs and the provisioning network.

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