python-masakariclient — Scenarios

Scenarios — 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

Participants are the openstack process, Keystone and Masakari. The sequences were observed against a local stub, which is not Masakari; the masakari engine's part is [inferred] from its own spec. Every scenario begins with authentication and one discovery, drawn only in the first.

1. Declare a segment and a host, by name

sequenceDiagram
  participant U as User
  participant C as openstack
  participant K as Keystone
  participant M as Masakari
  U->>C: segment create seg-a auto COMPUTE
  C->>K: HTTP POST /v3/auth/tokens
  K-->>C: 201 token and catalog
  C->>M: HTTP GET /instance-ha/v1 (discovery)
  M-->>C: 200 version 1.3, min 1.0
  C->>M: POST /segments (instance-ha 1.3)
  alt name taken
    M-->>C: 409
    C-->>U: exit 1, ConflictException
  else created
    M-->>C: 201 segment with uuid
    C->>M: GET /segments/{uuid}
    M-->>C: 200
    C-->>U: table, exit 0
  end
  U->>C: segment host create compute-1 COMPUTE SSH seg-a
  C->>M: GET /segments (name lookup, every page)
  M-->>C: 200 segments
  C->>M: POST /segments/{uuid}/hosts
  M-->>C: 201 host with uuid
  C->>M: GET /segments/{uuid}/hosts/{uuid}
  M-->>C: 200
  C-->>U: table, exit 0

Where to look: if the GET after the write fails, the command exits 1 while the resource exists (masakariclient/osc/v1/segment.py:168). Run segment list before retrying.

2. Report a failure, and follow recovery

sequenceDiagram
  participant U as User or monitor
  participant C as openstack
  participant M as Masakari API
  participant E as Masakari engine
  U->>C: notification create COMPUTE_HOST compute-1 time payload
  C->>C: parse payload as JSON
  alt invalid JSON
    C-->>U: exit 1, Expecting value… (no request)
  end
  C->>M: POST /notifications
  alt unknown host
    M-->>C: 400
    C-->>U: exit 1, BadRequestException
  else already in progress
    M-->>C: 409
    C-->>U: exit 1, ConflictException
  else accepted
    M-->>C: 202 notification_uuid
    M-)E: AMQP (see reverse-spec-masakari)
    C->>M: GET /notifications/{uuid}
    M-->>C: 200 status new or later
    C-->>U: table, exit 0
  end
  loop the user polls, the CLI has no wait option
    U->>C: notification show uuid
    C->>M: GET /notifications/{uuid}
    M-->>C: status, recovery_workflow_details (1.1 or above)
  end
  U->>C: notification vmove list uuid
  C->>M: GET /notifications/{uuid}/vmoves
  M-->>C: vmoves

Where to look: exit 0 only means the notification was accepted. Recovery failures show in status and recovery_workflow_details.

3. Delete segments: the failure that exits 0

sequenceDiagram
  participant U as Script
  participant C as openstack
  participant M as Masakari
  U->>C: segment delete nope seg-b
  C->>M: GET /segments (lookup of nope)
  M-->>C: 200, no match
  C->>M: DELETE /segments/nope
  M-->>C: 404
  C-->>U: stdout: NotFoundException… (loop continues)
  C->>M: GET /segments (lookup of seg-b)
  M-->>C: 200
  C->>M: DELETE /segments/{uuid}
  alt in use
    M-->>C: 409
    C-->>U: stdout: ConflictException…
  else
    M-->>C: 204
    C-->>U: stdout: Segment deleted: seg-b
  end
  C-->>U: exit 0 in every case

Where to look: stdout, since the exit code says nothing (masakariclient/osc/v1/segment.py:271). Check with segment show. segment host delete does exit 1.

4. Version negotiation that does not negotiate

sequenceDiagram
  participant U as User
  participant C as openstack
  participant M as Masakari
  U->>C: segment list (default 1.3)
  C->>M: GET /instance-ha/v1 without a token
  alt 401
    M-->>C: 401
    C->>M: GET /instance-ha/v1 with a token
  end
  alt maximum 1.3 or more
    M-->>C: version 1.3
    C->>M: GET /segments (instance-ha 1.3)
    M-->>C: 200
    C-->>U: table with is_enabled
  else maximum 1.2
    M-->>C: version 1.2
    C-->>U: exit 1, A default microversion… (no request)
  else no version document
    M-->>C: 404
    C->>M: GET /segments (instance-ha 1.3, unchecked)
  end

Where to look: for "A default microversion…", pass --os-ha-api-version with the service's maximum.

5. `--limit` walks every page

sequenceDiagram
  participant U as User
  participant C as openstack
  participant M as Masakari
  U->>C: segment list --limit 1
  C->>M: GET /segments?limit=1
  M-->>C: segment id 1
  C->>M: GET /segments?marker=1&limit=1
  M-->>C: segment id 2
  C->>M: GET /segments?marker=2&limit=1
  M-->>C: segment id 3
  C->>M: GET /segments?marker=3&limit=1
  M-->>C: empty
  C-->>U: 3 rows, exit 0

Where to look: a small --limit costs more requests and returns everything. Use it only as a page size.

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