OpenKeel: the sovereign French Cloud solution of the inherent group, with a European reach Discover inherent

Get started

Reverse-spec · Clients

osc-placement — Summary

Reverse-specification of osc-placement — branch stable/2026.2

Branch stable/2026.2 @ 402610a21872 (4.9.1 + 2 maintenance commits) — repository https://opendev.org/openstack/osc-placement — analysed on 2026-10-28

  • Scope: all non-test code (13 modules, 2,436 lines). The functional tests serve as the source of the client contract.
  • References are file:line relative to the repository root. [inferred] marks a statement that was not followed to the end in the code.

Files of this specification

FileContent
01-cli-commands_stable-2026.2.mdshared mechanics (plugin, microversion negotiation, client-side checks), the 31 commands with their class, minimum microversion and Placement calls
02-errors_stable-2026.2.mdtranslation of Placement 4xx into osc-lib exceptions, client-side errors, negotiation errors
03-interactions_stable-2026.2.mdKeystone (catalog) and Placement (headers, query strings, read-modify-write sequences)
04-scenarios_stable-2026.2.md4 scenarios: negotiation, allocation set, inventory on an aggregate, allocation candidates with groups
05-async-processing_stable-2026.2.mdnone (short-lived CLI process)
06-change-history_stable-2026.2.md2 maintenance commits; nothing to carry over
07-rewrite-pack_stable-2026.2.mdclient contract osc-placement → Placement, and a replayable suite of 928 invocations (928/928 identical against Placement)

Overview

osc-placement is the plugin of the openstack command line that drives Placement: resource providers, inventories, allocations, resource classes, traits, aggregates, usages and allocation candidates. Each command:

  1. checks the microversion locally;
  2. sends one to three REST calls to Placement (through keystoneauth and the Keystone catalog);
  3. displays the result.
ProcessEntry pointRole
openstack (python-openstackclient)entry points openstack.cli.extension = placement and openstack.placement.v1 (setup.cfg)loads the plugin and its 31 commands (osc_placement/plugin.py)

Key figures

31 commands; 21 microversions declared plus negotiation (osc_placement/version.py:21-55); default negotiated microversion 1.29; 0 exception classes of its own; 0 background processing. Tests: 160 functional tests, 928 CLI invocations, 1,381 HTTP exchanges recorded.

Points of attention

  1. Default 1.29: negotiation never goes above 1.29. Consumer types (1.38) and in: traits (1.39) need --os-placement-api-version.
  2. Read-modify-write without retry: allocation set, inventory set --amend, trait set and aggregate set read the generation, then write. A concurrent change gives a 409 shown to the user.
  3. Dependency on the Placement error format: errors[0].detail (last line) on every 4xx, and errors[0].max_version on a 406. Without them, the CLI crashes with KeyError.
  4. **inventory set --aggregate is not atomic**: partial failures, reported at the end.

Blind spots / [inferred]

  • The behaviour of osc-lib and openstackclient (argument parsing, output formatters) was not analysed: only their use by the plugin.
  • Negotiation against a server older than 1.29 is described from the code, not exercised by the recorded tests.

Source: reverse-spec-osc-placement/00-summary_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.