python-ironicclient — Cli commands

CLI commands — python-ironicclient — branch stable/2026.2

Branch stable/2026.2 @ af2ceeb9c4f2 — repository https://opendev.org/openstack/python-ironicclient — analysed on 2026-11-01

python-ironicclient exposes no API of its own. It is a **plugin of the openstack command line**, plus a separate baremetal shell. Both turn commands into calls to the Ironic REST API. Its contract with the outside world is the requests it sends: see interactions and the client contract.

[observed] means seen against a local stub, which is not Ironic.

1. Shared mechanics

Plugin and command loading

• Plugin: openstack.cli.extension = baremetal (pyproject.toml:45, ironicclient/osc/plugin.py:17), loaded by openstackclient:openstackclient/common/clientmanager.py:279. Commands are in openstack.baremetal.v1 (pyproject.toml:47), one entry per command.
• Base classes: ironicclient/osc/command.py:49 only adds typing to the osc-lib and cliff classes. Output type follows from the class: Lister (24 commands), ShowOne (28), Command with no table (66).
• Client construction: ironicclient/osc/plugin.py:53 builds one ironicclient.v1.client.Client per process, on first use. It takes the session from osc-lib and resolves the endpoint at once from the catalog, with baremetal_endpoint_override taking priority (osc-lib:osc_lib/clientmanager.py:285). The client does not read the version documents of the service. It passes no max_retries, so the defaults apply (ironicclient/common/http.py:57).

API version selection

The option is --os-baremetal-api-version (env OS_BAREMETAL_API_VERSION), ironicclient/osc/plugin.py:103. Values are 1, 1.1 to 1.115, latest.

Negotiation itself is in 03 § 3.

Client-side checks

• Version gates: nearly all version checks are the server's. The exceptions are runbooks, at 1.112: --description on create, set and unset (ironicclient/osc/v1/baremetal_runbook.py:119, ironicclient/osc/v1/baremetal_runbook.py:256, ironicclient/osc/v1/baremetal_runbook.py:359) and the 4 trait operations (ironicclient/v1/runbook.py:174, ironicclient/v1/runbook.py:206, ironicclient/v1/runbook.py:240, ironicclient/v1/runbook.py:270). check_api_version_support compares with the version the client is set to, not with the server's (ironicclient/common/utils.py:522), and accepts an unparsable version.
• List arguments: a negative --limit is refused before any request, for example ironicclient/osc/v1/baremetal_node.py:958 [observed]. --fields choices come from the *_DETAILED_RESOURCE tables of ironicclient/v1/resource_fields.py:269.
• Exclusive arguments: --clean-steps or --runbook is required on clean (ironicclient/osc/v1/baremetal_node.py:338). --runbook with --disable-ramdisk is refused at ironicclient/osc/v1/baremetal_node.py:117 [observed].

Value conversion

• **key=value in create and in --extra-style options**: split on the first =, and the value is parsed as JSON if possible (ironicclient/common/utils.py:52), so --extra a=1 gives a number.
• **set and unset send a JSON Patch**: args_array_to_patch builds add or remove operations (ironicclient/common/utils.py:108). set uses add, never replace. Each value goes through the same JSON parsing, so --name 123 sends a number [observed].
• JSON arguments (--steps, --deploy-steps, --network-data, and so on) accept a JSON string, a YAML or JSON file, or - for stdin (ironicclient/common/utils.py:449). A file is checked first (ironicclient/common/utils.py:403).

Several resources in one command

Lists

--limit absent: one request, next is ignored. --limit 0: follow next to the end. --limit N: send limit=N, follow next until N items are there (ironicclient/common/base.py:189) [observed]. --marker is passed through. --sort is applied by the client, on the page received (ironicclient/osc/v1/baremetal_node.py:994). --long asks for detail, --fields for a subset; they exclude each other in the parser and in the manager (ironicclient/v1/node.py:1453).

2. Functional description by resource

Nodes (baremetal node, 51 commands)

A node is one physical server managed by Ironic. Commands fall into groups:

• Registration: create needs --driver. It sends a POST /v1/nodes holding only the options given (ironicclient/osc/v1/baremetal_node.py:668), and hides links, ports, portgroups, states and volume from the result (ironicclient/osc/v1/baremetal_node.py:686). delete unregisters.
• Read: list has 27 filter and display options, translated at ironicclient/v1/node.py:1457. show --instance looks a node up by Nova instance, through GET /v1/nodes/detail?instance_uuid=, and reports Not Found unless exactly one node matches (ironicclient/v1/node.py:363) [observed]. validate shows the result per driver interface (ironicclient/osc/v1/baremetal_node.py:2126).
• Provision state: 13 commands send PUT /v1/nodes/{id}/states/provision with a target (ironicclient/v1/node.py:785). The command name and the target often differ: | Command | Target | --wait expects | Poll interval | Extra | |---|---|---|---|---| | manage | manage | manageable | 2 s | | | provide | provide | available | 10 s | | | inspect | inspect | manageable | 2 s | | | deploy | active | active | 10 s | --config-drive, --deploy-steps | | undeploy | deleted | available | 10 s | | | rebuild | rebuild | active | 10 s | --config-drive, --deploy-steps | | clean | clean | manageable | 10 s | --clean-steps or --runbook; --disable-ramdisk | | service | service | active | 10 s | --service-steps or --runbook; --disable-ramdisk | | rescue | rescue | rescue | 10 s | --rescue-password required | | unrescue | unrescue | active | 10 s | | | adopt | adopt | active | 2 s | | | abort | abort | no --wait | | | | unhold | unhold | no --wait | | | Sources: ironicclient/v1/utils.py:27, ironicclient/osc/v1/baremetal_node.py:61. These calls only start the action: the response comes before the end of it. --wait is client-side polling, see 05. The response code and the node states come from Ironic; see reverse-spec-ironic/.
• Config drive (ironicclient/v1/node.py:787): a JSON object is sent as is. A file is read, and sent as JSON if it holds JSON, otherwise as text. A directory is made into an ISO by a local binary (ironicclient/common/utils.py:261). Any other string fails, despite the help.
• Power and boot: power on, power off [--soft], reboot [--soft] with --power-timeout (ironicclient/v1/node.py:572); soft maps to soft power off and soft rebooting [observed]. boot device set|show, boot mode set, secure boot on|off, inject nmi, console enable|disable|show, maintenance set|unset.
• Attributes: set and unset cover the fields of ironicclient/osc/v1/baremetal_node.py:1689, interfaces, properties, extra, driver_info, instance_info and network_data. --target-raid-config uses its own PUT .../states/raid, sent first, because the node may be renamed in the same command (ironicclient/osc/v1/baremetal_node.py:1678). --reset-interfaces needs --driver and goes as a query parameter (ironicclient/v1/node.py:390). No value given: a warning Please specify what to set., exit 0 (ironicclient/osc/v1/baremetal_node.py:1748).
• Traits: trait add|list|remove. add trait and remove trait are older names of the same classes, kept for compatibility (pyproject.toml:74). remove --all is one DELETE .../traits.
• VIFs: vif attach|detach|list, with free --vif-info key=value entries; id is reserved (ironicclient/v1/node.py:494).
• Inventory data: bios setting list|show, firmware list, history list|get, inventory save, children list. inventory save prints JSON on stdout, or writes --file (ironicclient/osc/v1/baremetal_node.py:2604).
• Vendor passthru: passthru list, passthru call with --http-method and --arg. The answer is printed raw (ironicclient/osc/v1/baremetal_node.py:1130).

Ports, port groups, volume connectors and targets

The NICs and storage links of a node. CRUD on /v1/ports, /v1/portgroups, /v1/volume/connectors, /v1/volume/targets. port show --address and port group show --address look up through a filtered list and need exactly one match (ironicclient/v1/port.py:76, ironicclient/v1/portgroup.py:105). volume target create refuses a negative --boot-index (ironicclient/osc/v1/baremetal_volume_target.py:99).

Allocations

Ask Ironic to pick a node: allocation create needs --resource-class, or --node for a backfill (ironicclient/osc/v1/baremetal_allocation.py:103). --wait polls every second (ironicclient/v1/allocation.py:89). Failure shows last_error.

Chassis, conductors, shards, drivers

• chassis: plain CRUD on /v1/chassis.
• conductor list|show, shard list: read only.
• driver list always sends detail= (ironicclient/osc/v1/baremetal_driver.py:74). driver show hides links and properties. driver property list, driver raid property list, driver passthru list|call.

Deploy templates, runbooks, inspection rules

• deploy template: CRUD on /v1/deploy_templates, --steps required on create.
• runbook: CRUD on /v1/runbooks plus trait add|list|remove. --public and --disable-ramdisk take an explicit boolean string (ironicclient/common/utils.py:324).
• inspection rule: CRUD on /v1/inspection_rules, --actions required, --conditions optional, JSON values. See the defects in 02 § 5. No unit test covers these 6 commands.

Bulk creation (baremetal create)

Reads .yaml or .json files that may nest chassis → nodes → portgroups → ports (ironicclient/v1/create_resources.py:26). It first validates all files against a small JSON schema, and creates nothing if one fails (ironicclient/v1/create_resources.py:69). It then creates each resource in turn, skips the children of a failed parent, and reports all errors at the end (ironicclient/v1/create_resources.py:80). Nothing is rolled back. traits on a node goes through a separate PUT (ironicclient/v1/create_resources.py:184).

3. The baremetal shell

ironicclient/shell.py:108 is a cliff App with the same entry points and with the baremetal prefix removed from the names (ironicclient/shell.py:95). Differences from the plugin:

With no endpoint and no credentials: The Bare Metal API endpoint cannot be detected…, exit 1 [observed].

4. Python API

Both shells use it, and other tools can too (ironicclient/client.py:30, ironicclient/client.py:132).

• get_client('1', endpoint=…, token=…) picks the auth type: admin_token or none with an endpoint, token with a token and URL, otherwise password (ironicclient/client.py:74). It does not read clouds.yaml (ironicclient/client.py:88).
• Client holds one manager per resource (ironicclient/v1/client.py:105).
• Each manager method takes os_ironic_api_version and global_request_id, for one request (ironicclient/common/base.py:223).
• Passing no version uses the cache, or 1.9 (ironicclient/common/http.py:44, ironicclient/v1/client.py:82). This is the only path that reads the cache, and the default differs a lot from the 1.115 of the shells.
• Methods without a command, from _rewrite/python-api-probe_stable-2026.2.json: chassis.list_nodes, driver.update, driver.delete, events.create, node.list_ports, node.list_volume_connectors, node.list_volume_targets, node.states, portgroup.list_ports. driver.update and driver.delete target routes that Ironic's reverse-spec does not list, and that were not found in its driver controller [inferred].
• wait_for_provision_state and allocation.wait are usable directly, with a custom poll_delay_function.

5. Which request each option produces

_rewrite/wire-options_stable-2026.2.json has one run per optional argument: 397 runs against the {} stub. options_on_wire in _rewrite/client-contract_stable-2026.2.json is the short form: route, query parameters, body keys or patch paths. Example, --chassis on node list becomes the query parameter chassis_uuid, and --port-group on port create becomes the body key portgroup_uuid.

6. All commands

Generated from _rewrite/client-contract_stable-2026.2.json. "Requests observed" joins the runs against the 404 and {} stubs with synthetic arguments, and reflects the client only. A few commands need one option to send anything; it is added by the EXTRA table of _rewrite/probe_plugin_stable-2026.2.py. {id} stands for any name or UUID.

(top level) (1)

allocation (6)

chassis (6)

conductor (2)

deploy template (6)

driver (6)

inspection rule (6)

node (51)

port (6)

port group (6)

runbook (9)

shard (1)

volume connector (6)

volume target (6)

Source: reverse-spec-python-ironicclient/01-cli-commands_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.