python-masakariclient — Cli commands

CLI commands — 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

python-masakariclient has no API of its own. Its interface is the 15 commands, and its contract with the outside is what they send to Masakari (interactions, client contract). [observed] means seen against a local stub, which is not Masakari. Request sequences come from the lifecycle scenario of [_rewrite/wire-scenarios_stable-2026.2.json](_rewrite/wire-scenarios_stable-2026.2.json). Machine-readable arguments: [_rewrite/cli-commands_stable-2026.2.json](_rewrite/cli-commands_stable-2026.2.json).

1. Shared mechanics

Loading: entry point ha = masakariclient.plugin in openstack.cli.extension (setup.cfg:29). The shell reads API_NAME and the option, and adds the group openstack.ha.v<major> (openstackclient:openstackclient/shell.py:150). Only openstack.ha.v1 exists (setup.cfg:32), so a major version other than 1 removes the commands [observed]. The plugin is registered as a lazy attribute ha of the client manager (openstackclient:openstackclient/common/clientmanager.py:251).
Version option: --os-ha-api-version, env OS_HA_API_VERSION, default 1.3 (masakariclient/plugin.py:22, masakariclient/plugin.py:51). API_VERSIONS (masakariclient/plugin.py:34) only drives a warning (openstackclient:openstackclient/shell.py:130).
Client: make_client builds a second openstack.connection.Connection on the CLI's session, region and interface, with ha_api_version set, and returns con.instance_ha (masakariclient/plugin.py:38). The kwarg reaches the config through the service-type alias ha (openstacksdk:openstack/config/cloud_region.py:591).
What the version option does (03 § 3 has the table): a value with a non-zero minor (1.1 to 1.3) becomes the proxy's default_microversion, sent on every request; 1 and 1.0 set none (openstacksdk:openstack/config/cloud_region.py:115).
Gates read masakari_client.default_microversion, not the version actually sent. When it is unset, they all fail closed: no is_enabled, no recovery_workflow_details.
Name lookup, get_uuid_by_name (masakariclient/common/utils.py:90): a UUID-like value goes straight through (oslo_utils.uuidutils.is_uuid_like). Otherwise it lists all segments, or all hosts of the segment, walking every page, and takes the first exact match. If nothing matches, it returns the name unchanged, which then goes to the server as an ID [observed]. Each name costs at least one list. Notifications and vmoves take UUIDs only.
List arguments, format_sort_filter_params (masakariclient/common/utils.py:58):
- --limit, --marker: passed as strings, unchecked;
- --sort a:asc,b: becomes repeated sort_key and sort_dir; no direction means desc (masakariclient/common/utils.py:74); anything else is refused;
- --filters: k=v; a single --filters is split on ;, several are not (masakariclient/common/utils.py:29); a repeated key gives a list and a repeated parameter (masakariclient/common/utils.py:40).
What then happens to filters in the SDK [observed]: mapped keys become query parameters, including is_enabled → enabled and generated_since → generated-since (openstacksdk:openstack/instance_ha/v1/segment.py:57, openstacksdk:openstack/instance_ha/v1/notification.py:89); other names of body attributes filter on the client (openstacksdk:openstack/resource.py:2236); anything else is dropped (openstacksdk:openstack/resource.py:340).
Unset options are removed before the call (masakariclient/common/utils.py:50), so an update sends only what was given. With nothing given, the SDK sends no PUT (openstacksdk:openstack/resource.py:1921), and the command shows the resource and exits 0 [observed].
Write then read: create and update commands discard the write's response, apart from the UUID, and show a fresh GET.
Every request carries X-Auth-Token and OpenStack-API-Version: instance-ha <version> when a default microversion is set [observed]. See 03.
Authorisation is the service's: all rules default to admin (masakari:masakari/policies/base.py:21). The client checks nothing.

2. Functional description

Failover segments

A segment groups hosts that protect each other, with a recovery_method. Actor: an administrator.

**segment create** (masakariclient/osc/v1/segment.py:107). Purpose: declare a failover group. Rules: recovery_method among auto, reserved_host, auto_priority, rh_priority (masakariclient/osc/v1/segment.py:120); service_type is free text; --is_enabled is parsed strictly by strutils.bool_from_string, and is sent as enabled only at 1.2 or above (masakariclient/osc/v1/segment.py:154). Flow: POST /segments, then GET /segments/{uuid}. [observed]

Argument	Required	Choices	Help
`<name>`	yes		Name of segment.
`<recovery_method>`	yes	auto, reserved_host, auto_priority, rh_priority	Recovery method of segment. The supported options are: auto, reserved_host, auto_priority, rh_priority.
`<service_type>`	yes		Service type of segment.
`--is_enabled`	no		The enabled flag of this segment. Supported after microversion 1.2.
`--description`	no		Description of segment.

**segment update** (masakariclient/osc/v1/segment.py:172). Purpose: change attributes. Flow: lookup if a name; PUT /segments/{uuid} with the given fields only, omitted when there are none; GET /segments/{uuid}. [observed]

Argument	Required	Choices	Help
`<segment>`	yes		Name or ID of the segment to update.
`--name`	no		Name of segment.
`--recovery_method`	no	auto, reserved_host, auto_priority, rh_priority	Recovery method of segment. The supported options are: auto, reserved_host, auto_priority, rh_priority
`--service_type`	no		Service type of segment.
`--is_enabled`	no		The enabled flag of this segment. Supported after microversion 1.2.
`--description`	no		Description of segment.

**segment list** (masakariclient/osc/v1/segment.py:31). GET /segments, with every page. Columns: uuid name description service_type recovery_method, plus is_enabled at 1.2 or above (masakariclient/osc/v1/segment.py:69). The integer id needed for --marker is not shown.

Argument	Required	Help
`--limit`	no	Limit the number of segments returned
`--marker`	no	Only return segments that appear after the given segment ID
`--sort`	no	Sorting option which is a string containing a list of keys separated by commas. Each key can be optionally appended by a sort direction (:asc or :desc). The valid sort keys are: ['type', 'name', 'created_at', 'updated_at']
`--filters`	no	Filter parameters to apply on returned segments. This can be specified multiple times, or once with parameters separated by a semicolon. The valid filter keys are: ['recovery_method', 'service_type']

**segment show** (masakariclient/osc/v1/segment.py:88). Lookup if a name, then GET /segments/{uuid}. Fields: created_at updated_at uuid name description id service_type recovery_method, plus is_enabled at 1.2 or above (masakariclient/osc/v1/segment.py:283).

Argument	Required	Choices	Help
`<segment>`	yes		Segment to display (name or ID)

**segment delete** (masakariclient/osc/v1/segment.py:250). Takes one or more names or IDs. For each: lookup if a name, DELETE /segments/{uuid}, print Segment deleted: <given value>. Any exception is printed and the loop continues; exit 0 (masakariclient/osc/v1/segment.py:271). Defect 1 of 02.

Argument	Required	Choices	Help
`<segment>`	yes		Name or ID of segment(s) to delete

Hosts

A host belongs to a segment; reserved and on_maintenance drive what recovery may do with it. Positional order differs: segment host create <name> <type> <control_attributes> <segment_id>, while the others begin with the segment.

**segment host create** (masakariclient/osc/v1/host.py:116). Lookup of the segment; POST /segments/{sid}/hosts; GET /segments/{sid}/hosts/{uuid}. --reserved and --on_maintenance accept only True and False (masakariclient/osc/v1/host.py:144), and are sent as JSON strings: {"host": {"reserved": "True", …}} [observed]. The service's schema accepts them (masakari:masakari/api/validation/parameter_types.py:151).

Argument	Required	Choices	Help
`<name>`	yes		Name of host.
`<type>`	yes		Type of host.
`<control_attributes>`	yes		Attribute about control.
`<segment_id>`	yes		Name or ID of segment.
`--reserved`	no	True, False	Host reservation. The supported options are: True, False.
`--on_maintenance`	no	True, False	Maintenance status of host. The supported options are: True, False.

**segment host update** (masakariclient/osc/v1/host.py:183). Lookup of segment and host; PUT with the given fields only; GET. [observed]

Argument	Required	Choices	Help
`<segment_id>`	yes		Name or ID of segment.
`<host>`	yes		Name or ID of the Host
`--reserved`	no	True, False	Host reservation. The supported options are: True, False.
`--on_maintenance`	no	True, False	Maintenance status of host. The supported options are: True, False.
`--name`	no		Name of host.
`--type`	no		Type of host.
`--control_attributes`	no		Attributes about control.

**segment host list** (masakariclient/osc/v1/host.py:29). Lookup; GET /segments/{sid}/hosts. Columns: uuid name type control_attributes reserved on_maintenance failover_segment_id (masakariclient/osc/v1/host.py:75).

Argument	Required	Help
`<segment_id>`	yes	Name or ID of segment.
`--limit`	no	Limit the number of hosts returned
`--marker`	no	Only return hosts that appear after the given host ID
`--sort`	no	Sorting option which is a string containing a list of keys separated by commas. Each key can be optionally appended by a sort direction (:asc or :desc). The valid sort keys are: ['type', 'name', 'created_at', 'updated_at']
`--filters`	no	Filter parameters to apply on returned hosts. This can be specified multiple times, or once with parameters separated by a semicolon. The valid filter keys are: ['failover_segment_id', 'type', 'on_maintenance', 'reserved']

**segment host show** (masakariclient/osc/v1/host.py:88). Up to three requests: lookup of segment, lookup of host, GET …/hosts/{uuid}. Fields at masakariclient/osc/v1/host.py:300; id is not among them.

Argument	Required	Choices	Help
`<segment_id>`	yes		Name or ID of segment.
`<host>`	yes		Name or ID of the Host

**segment host delete** (masakariclient/osc/v1/host.py:262). Lookups, then DELETE with ignore_missing=False (masakariclient/osc/v1/host.py:287); prints Host deleted: <given value>. Failures exit 1, unlike segment delete.

Argument	Required	Choices	Help
`<segment_id>`	yes		Name or ID of segment.
`<host>`	yes		Name or ID of the Host

Notifications

A notification tells Masakari that a host, VM or process failed. Actor: an administrator or, in production, masakari-monitors, which calls the SDK directly. There is no update or delete.

**notification create** (masakariclient/osc/v1/notification.py:95). <type> among COMPUTE_HOST, VM, PROCESS; <payload> is parsed as JSON locally; <hostname> and <generated_time> are not checked. Flow: POST /notifications, then GET /notifications/{notification_uuid} (masakariclient/osc/v1/notification.py:134). Outcome: the service answers 202 and recovery runs later; the status shown is that of the moment, usually new (05).

Argument	Required	Choices	Help
`<type>`	yes	COMPUTE_HOST, VM, PROCESS	Type of failure. The supported options are: COMPUTE_HOST, VM, PROCESS.
`<hostname>`	yes		Hostname of notification.
`<generated_time>`	yes		Timestamp for notification. e.g. 2016-01-01T01:00:00.000
`<payload>`	yes		JSON string about failure event.

**notification list** (masakariclient/osc/v1/notification.py:26). GET /notifications. Columns at masakariclient/osc/v1/notification.py:64; payload is printed as a Python repr [observed].

Argument	Required	Help
`--limit`	no	Limit the number of notifications returned
`--marker`	no	Only return notifications that appear after the given notification ID
`--sort`	no	Sorting option which is a string containing a list of keys separated by commas. Each key can be optionally appended by a sort direction (:asc or :desc). The valid sort keys are: ['type', 'created_at', 'updated_at']
`--filters`	no	Filter parameters to apply on returned notifications. This can be specified multiple times, or once with parameters separated by a semicolon. The valid filter keys are: ['source_host_uuid', 'type', 'status', generated-since]

**notification show** (masakariclient/osc/v1/notification.py:77). GET /notifications/{uuid}. Fields at masakariclient/osc/v1/notification.py:147, plus recovery_workflow_details at 1.1 or above (masakariclient/osc/v1/notification.py:161), printed as a Python repr of the nested list [observed].

Argument	Required	Choices	Help
`<notification>`	yes		UUID of notification to display

VM moves

Records of each instance moved while processing a COMPUTE_HOST notification.

**notification vmove list** (masakariclient/osc/v1/vmove.py:29). GET /notifications/{id}/vmoves. Columns at masakariclient/osc/v1/vmove.py:72. The SDK renames instance_uuid and instance_name to server_id and server_name (openstacksdk:openstack/instance_ha/v1/vmove.py:47).

Argument	Required	Help
`<notification_id>`	yes	UUID of notification.
`--limit`	no	Limit the number of vmoves returned
`--marker`	no	Only return vmoves that appear after the given vmove ID
`--sort`	no	Sorting option which is a string containing a list of keys separated by commas. Each key can be optionally appended by a sort direction (:asc or :desc). The valid sort keys are: ['type', 'status', 'start_time', 'end_time']
`--filters`	no	Filter parameters to apply on returned vmoves. This can be specified multiple times, or once with parameters separated by a semicolon. The valid filter keys are: ['type', 'status'

**notification vmove show** (masakariclient/osc/v1/vmove.py:88). GET /notifications/{id}/vmoves/{vmove_id}. Fields at masakariclient/osc/v1/vmove.py:119. The commands have no gate: the documented minimum, 1.3, is not checked by the client, nor by the service (masakari:masakari/api/openstack/ha/vmoves.py:38).

Argument	Required	Choices	Help
`<notification_id>`	yes		UUID of COMPUTE_NODE type notification.
`<vmove_id>`	yes		UUID of the VMove

3. Summary

Command	Class	Requests (without a name lookup) [observed]	Output
`segment create`	`masakariclient/osc/v1/segment.py:107`	`POST /segments`, `GET /segments/{id}`	single
`segment update`	`masakariclient/osc/v1/segment.py:172`	`PUT /segments/{id}`, `GET /segments/{id}`	single
`segment list`	`masakariclient/osc/v1/segment.py:31`	`GET /segments`	list
`segment show`	`masakariclient/osc/v1/segment.py:88`	`GET /segments/{id}`	single
`segment delete`	`masakariclient/osc/v1/segment.py:250`	`DELETE /segments/{id}` per value	text on stdout
`segment host create`	`masakariclient/osc/v1/host.py:116`	`POST …/hosts`, `GET …/hosts/{id}`	single
`segment host update`	`masakariclient/osc/v1/host.py:183`	`PUT …/hosts/{id}`, `GET …/hosts/{id}`	single
`segment host list`	`masakariclient/osc/v1/host.py:29`	`GET …/hosts`	list
`segment host show`	`masakariclient/osc/v1/host.py:88`	`GET …/hosts/{id}`	single
`segment host delete`	`masakariclient/osc/v1/host.py:262`	`DELETE …/hosts/{id}`	text on stdout
`notification create`	`masakariclient/osc/v1/notification.py:95`	`POST /notifications`, `GET /notifications/{id}`	single
`notification list`	`masakariclient/osc/v1/notification.py:26`	`GET /notifications`	list
`notification show`	`masakariclient/osc/v1/notification.py:77`	`GET /notifications/{id}`	single
`notification vmove list`	`masakariclient/osc/v1/vmove.py:29`	`GET /notifications/{id}/vmoves`	list
`notification vmove show`	`masakariclient/osc/v1/vmove.py:88`	`GET /notifications/{id}/vmoves/{vmove_id}`	single

Lists and single outputs accept the usual cliff options (-f, -c), not specified here.

4. Lifecycle of a notification, as the client sees it

The client only reads status. It does not wait.

stateDiagram-v2
  [*] --> new: openstack notification create (POST, 202)
  new --> running: masakari engine, not visible to the CLI
  new --> ignored: masakari engine
  running --> finished: engine
  running --> failed: engine
  running --> error: engine
  error --> running: engine periodic retry
  finished --> [*]
  failed --> [*]
  ignored --> [*]

The state names come from the service (masakari:masakari/objects/fields.py:167), not from this repository, and the transitions are [inferred]; see reverse-spec-masakari.

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