python-masakariclient — Interactions

Interactions — python-masakariclient — branch stable/2026.2

Branch stable/2026.2 @ 073cd2cca082 (8.9.0 + 2 commits) — repository https://opendev.org/openstack/python-masakariclient — analysed on 2026-11-01

Database, RabbitMQ and cache: none. All exchanges are outbound HTTP through keystoneauth1. No local file is read by the plugin itself. [observed] means seen against a local stub, which is not Masakari.

1. Stack

make_client (masakariclient/plugin.py:38) creates openstack.connection.Connection(session=…, interface=…, region_name=…, ha_api_version=…) and returns .instance_ha, an openstack.instance_ha.v1._proxy.Proxy (openstacksdk:openstack/instance_ha/instance_ha_service.py:19). It shares the CLI's keystoneauth session, so one token. Resources: openstacksdk:openstack/instance_ha/v1/segment.py:18, openstacksdk:openstack/instance_ha/v1/host.py:18, openstacksdk:openstack/instance_ha/v1/notification.py:40, openstacksdk:openstack/instance_ha/v1/vmove.py:18.

Because this Connection gets a session and no parsed config, keys of the cloud such as an endpoint override may not reach it [inferred, not exercised].

2. Keystone and catalog

Step	Request [observed]	Note
Discovery	`GET {auth_url}`	300 with `versions.values` on the stub
Authentication	`POST /v3/auth/tokens`	body with `password`, scope project
Result	`X-Subject-Token`, and a token holding `catalog`	one authentication per process

Catalog type	Result [observed]
`instance-ha`	works
`ha`	works: alias from os-service-types
`masakari`	`public endpoint for instance-ha service in RegionOne region not found`, exit 1
absent	`Service 'instance-ha' is disabled…`, exit 1, or exit 0 on `segment delete`

Endpoint URL form	Result [observed]
`…/instance-ha/v1/<project>`	requests go to `…/v1/<project>/segments`
`…/instance-ha/v1`	requests go to `…/v1/segments`. The service maps both (`masakari:masakari/api/openstack/__init__.py:100`)

3. Discovery and microversions

Discovery [observed]: one GET /instance-ha/v1, first without a token. On 401, it is retried with one and the command goes on. The stub's version document mirrors masakari:masakari/api/openstack/ha/versions.py:33 and masakari:masakari/api/openstack/ha/views/versions.py:66:

{"version": {"id": "v1.0", "status": "CURRENT", "version": "1.3", "min_version": "1.0", "updated": "2016-07-01T11:33:21Z",
             "links": [{"rel": "self", "href": "http://<stub>/instance-ha/v1/"}]}}

The tool's generic document announced 2.100 and had no GET /instance-ha/v1, which stopped the first probe there. If every discovery URL answers 404, the SDK goes on and sends the requests anyway, with the header unchecked [observed, no-discovery]: GET /instance-ha/v1 and GET /instance-ha/v1/p are both tried.

Version option [observed, versions and server-older, stub range 1.0 to 1.3]:

`--os-ha-api-version`	`default_microversion`	Header on segments	Header on the others	`is_enabled` shown and sent	`recovery_workflow_details`
default, `1.3`	1.3	1.3	1.3	yes	yes
`1.2`	1.2	1.2	1.2	yes	yes
`1.1`	1.1	1.1	1.1	no	yes
`1`, `1.0`	none	1.2	none	no	no
`1.latest`, `1.x`	none; warning	1.2	none	no	no
`1.99`	refused	none: exit 1	none
`abc`, `latest`, `2`, `2.0`		commands absent: exit 2

With a default microversion, the SDK sends it as is (openstacksdk:openstack/resource.py:1437), and checks it against the discovered range (openstacksdk:openstack/config/cloud_region.py:1263).
Without one, a resource with _max_microversion negotiates: segments, 1.2 (openstacksdk:openstack/instance_ha/v1/segment.py:36, openstacksdk:openstack/resource.py:1440). Hosts, notifications and vmoves send nothing.
.0 is not read as a microversion (openstacksdk:openstack/config/cloud_region.py:121).

4. Requests to Masakari

Aspect	Value [observed]
Headers	`X-Auth-Token`, `OpenStack-API-Version: instance-ha <v>`, `Accept: application/json` on lists and `Accept: /` on the other requests, `Content-Type: application/json` on bodies, `User-Agent` from keystoneauth; recorded per request in `_rewrite/wire-scenarios_stable-2026.2.json`, token masked
Body key	`segment`, `host`, `notification`
Field renames	`is_enabled` → `enabled` (`openstacksdk:openstack/instance_ha/v1/segment.py:55`); response `instance_uuid`, `instance_name` → `server_id`, `server_name`
Booleans	`enabled` is a JSON boolean; `reserved`, `on_maintenance` are strings `"True"`, `"False"`
Query	`limit`, `marker`, repeated `sort_key` and `sort_dir`, mapped filters
Pagination	after each non-empty page with `--limit`: `marker=<last id>&limit=<n>`; stops on an empty page (`openstacksdk:openstack/resource.py:2325`, `openstacksdk:openstack/resource.py:2434`). Without `--limit`, one request
Retry	only the 401 re-authentication; no retry on 409 or 5xx
Concurrency	sequential; one thread

Complete operation list: [_rewrite/api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md).

Sample frames [observed, stub]

openstack segment update seg-a --description new --is_enabled false, after the lookup GET /segments:

PUT /instance-ha/v1/p/segments/69eefb8f-ea73-503c-9634-5ff776a4e51d HTTP/1.1
OpenStack-API-Version: instance-ha 1.3
X-Auth-Token: ***
Content-Type: application/json

{"segment": {"description": "new", "enabled": false}}

openstack segment host create compute-1 COMPUTE SSH seg-a --reserved True --on_maintenance False:

POST /instance-ha/v1/p/segments/69eefb8f-ea73-503c-9634-5ff776a4e51d/hosts HTTP/1.1

{"host": {"type": "COMPUTE", "reserved": "True", "on_maintenance": "False", "name": "compute-1", "control_attributes": "SSH"}}

openstack notification create COMPUTE_HOST compute-1 2026-01-01T00:00:00.000 '{"event": "STOPPED", …}':

POST /instance-ha/v1/p/notifications HTTP/1.1

{"notification": {"type": "COMPUTE_HOST", "payload": {"event": "STOPPED", "host_status": "NORMAL", "cluster_status": "OFFLINE"}, "generated_time": "2026-01-01T00:00:00.000", "hostname": "compute-1"}}

openstack segment list --sort name:asc,type: GET /segments?sort_key=name&sort_key=type&sort_dir=asc&sort_dir=desc.

openstack notification list --filters generated_since=2026-01-01T00:00:00: GET /notifications?generated-since=2026-01-01T00%3A00%3A00. Both spellings of the key work.

JSON key order is not stable between runs [observed], so nothing may depend on it.

5. Other

No subprocess, no local binary, no terminal read: no command needed excluding from the probes. The commands print with print on stdout only in the two delete commands (masakariclient/osc/v1/segment.py:270, masakariclient/osc/v1/host.py:289).

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