python-ironicclient — Rewrite pack

Client contract (rewrite pack) — python-ironicclient — branch stable/2026.2

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

This pack serves two purposes:

• **Keep openstack baremetal working against a Go Bare Metal service** (openkeel-ironic), by stating what the client requires.
• Re-implement the client, using the machine-readable catalogue of commands.

No replay against Ironic was possible, or wanted, here. The client ran only against a local stub. Requirements below come from the client's code and its reaction to scripted answers. They are necessary, not sufficient: passing them does not mean behaving like Ironic. For the server's own behaviour, use reverse-spec-ironic/.

1. Contents of _rewrite/

Versions: python-ironicclient 6.3.1.dev2, osc-lib 4.7.0, cliff 4.16.0, python-openstackclient 10.3.1, keystoneauth1 5.17.0, Python 3.13.

To regenerate (with HOME set to an empty directory, OS_* unset, and <in from /dev/null: some unit test run hung with an open stdin and finished with it closed; the test was not isolated):

python -I -B _rewrite/extract_plugin_stable-2026.2.py <repo> python-ironicclient ironicclient _rewrite
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-404> --mode 404
python -I -B _rewrite/probe_plugin_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir-200> --mode 200 --options
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-1>/c.json <repo>/ironicclient/tests/unit <repo>
python -I -B _rewrite/capture_plugin_stable-2026.2.py <repo> _rewrite/cli-commands_stable-2026.2.json <run-2>/c.json <repo>/ironicclient/tests/unit <repo>
python -I -B _rewrite/python_api_probe_stable-2026.2.py _rewrite/cli-commands_stable-2026.2.json <dir>/api.json
python -I -B _rewrite/repro_scenarios_stable-2026.2.py <python> <dir>/repro.json
python -I -B _rewrite/build_contract_stable-2026.2.py . <dir-404>/wire-probe_stable-2026.2.json <dir-200>/wire-probe_stable-2026.2.json <dir-200>/wire-options_stable-2026.2.json <run-1>/c.json <run-2>/c.json <dir>/api.json <dir>/repro.json <ironic-routes.json>

Everything stays on 127.0.0.1. One scenario connects to a closed local port. The generic rewrite_pack.py and conformance_capture.py were not used: they expect a service or functional tests in-process, and this repository has only unit tests (.stestr.conf:2).

2. What the client requires from a Bare Metal service

Routes

[api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md) lists 114 routes. Those not in reverse-spec-ironic/_rewrite/routes-list_stable-2026.2.json are 15, and this is how they resolve:

If openkeel-ironic was built from that route list, these are worth checking first. This was not checked.

The 32 Ironic routes never sent by this client are at the end of the same file: agent routes (/v1/lookup, /v1/heartbeat), /v1/nodes/{id}/vmedia, /v1/nodes/{id}/management/indicators, /v1/nodes/{id}/allocation, /v1/nodes/{id}/portgroups, DELETE /v1/inspection_rules, among others. A service needs them for other clients, not for this one. No client command covers vmedia or indicators.

3. HTTP behaviour

No middleware to describe on the client side. The order of its handling is in 02 § 2.

4. For a rewrite of the client itself

Recommendation: keep the Python client and make the service compatible. It is the client users already have. Fixes to the defects belong upstream.

5. Conformance: what was proved

The vectors and probes were not replayed against a service or a rewrite, and nothing was compared with a live Ironic. The usual "replay is mandatory" bar is not met for service behaviour. Mocks also hide defects: defects 1, 2, 4 and 5 of 02 § 5 pass or escape the unit tests.

To close the gap: point probe_plugin_stable-2026.2.py at a devstack with Ironic stable/2026.2, then at openkeel-ironic, with seeded resources, and compare. That needs a lab, so it was out of scope here.

Classes without a unit vector (6)

All in ironicclient/osc/v1/baremetal_inspection_rule.py: CreateBaremetalInspectionRule, DeleteBaremetalInspectionRule, ListBaremetalInspectionRule, SetBaremetalInspectionRule, ShowBaremetalInspectionRule, UnsetBaremetalInspectionRule. No test file exists for them. Note that 127 vectors have no client call: they test parser failures or client-side checks.

6. Gaps found while building the pack

• The shared extractor found no static REST routes and no gates, since this client does not use openstacksdk. Routes come from the wire instead.
• The catalogue of errors is a floor: it walks from take_action, and misses the managers. 02 § 4 adds those by hand.
• reverse-spec-ironic/_rewrite/routes-list_stable-2026.2.json lacks some routes that exist in Ironic, listed above.
• --config-drive <directory> was not run.

7. Non-functional requirements

• Latency: each openstack process authenticates. Against an older server, it also pays the 406 and GET /v1 each time, since the cache is not read.
• Wait load: --wait fetches the full node every 2 to 10 seconds per node, with no field filter (ironicclient/v1/node.py:1127).
• Page size: without --limit, the first page is all the client gets, so the server's max_limit decides what users see.

8. Checklist for a Bare Metal service

• [ ] baremetal in the catalog, with the expected interface.
• [ ] Version headers on GET /v1, without a request version.
• [ ] 406, with those headers, above the maximum version.
• [ ] Errors as {"error_message": "<JSON string with faultstring>"}.
• [ ] No Retry-After outside 413, including at the proxy.
• [ ] 409 and 503 only for temporary states.
• [ ] /v1/nodes and /v1/nodes/?x=y both work; next links keep the prefix.
• [ ] Every route of api-surface_stable-2026.2.md marked CLI or CLI option is implemented, including the ones missing from the route list.
• [ ] Node, allocation, history, BIOS, validate and passthru shapes of § 2.
• [ ] The probes in _rewrite/ give the same routes and exit 0 with real resources.

Source: reverse-spec-python-ironicclient/07-rewrite-pack_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.