python-openstackclient — Scenarios

Scenarios — python-openstackclient — branch stable/2026.2

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

Routes are observed against the stub until its first error, and read from the source after that (marked static).

1. Starting up and authenticating (every command)

The process loads plugins and commands before any network call. A broken plugin only prints a warning.

sequenceDiagram
  autonumber
  actor U as User
  participant S as openstack (shell)
  participant KS as Keystone
  participant N as Service
  U->>S: openstack server show x
  S->>S: load entry points, add groups for API versions
  S->>S: read clouds.yaml and OS_* variables
  alt auth_required is false
    S-->>U: run without any request
  else auth_required is true
    S->>KS: GET auth_url (discovery)
    S->>KS: POST /v3/auth/tokens
    alt credentials refused or Keystone down
      KS-->>S: 401 or connection error
      S-->>U: stderr message, exit 1
    else
      KS-->>S: 201, X-Subject-Token, catalog
      S->>N: GET version document
      S->>N: command requests
    end
  end

Diagnostics: use --debug to see every request with its headers. Missing value auth-url… means that nothing was configured. public endpoint for … not found means that the catalog lacks the service: check openstack catalog list and --os-interface.

Sources: openstackclient/shell.py:94, openstackclient/shell.py:201, osc-lib:osc_lib/shell.py:509.

2. Finding a resource by name, then failing

sequenceDiagram
  autonumber
  actor U as User
  participant S as openstack
  participant N as Nova
  U->>S: openstack server show x
  S->>N: GET /servers/x (compute 2.100)
  alt found
    N-->>S: 200 server
    S-->>U: table, exit 0
  else 404
    N-->>S: 404
    S->>N: GET /servers/detail?name=x
    alt one match
      N-->>S: 200, one server
      S-->>U: table, exit 0
    else none or error
      N-->>S: 200 empty, or 404
      S-->>U: stderr, exit 1
    end
  end

Diagnostics: NotFoundException … detail?name=x shows the last URL tried, not the first. A 404 on an ID is normal: it is the signal for the fallback, so a service returning 500 there breaks name lookups.

3. Creating a server and waiting

sequenceDiagram
  autonumber
  actor U as User
  participant S as openstack
  participant G as Glance
  participant N as Nova
  participant Q as Neutron
  U->>S: server create --image i --flavor f --network n --wait srv
  S->>S: local checks of option combinations
  S->>G: GET /images/i, then fallback (static)
  S->>N: GET /flavors/f, then GET /flavors/detail
  S->>Q: GET /networks/n, then GET /networks?name=n (static)
  alt invalid combination or microversion too low
    S-->>U: CommandError, exit 1
  else
    S->>N: POST /servers (static)
    N-->>S: 202 server BUILD
    loop every 5 s
      S->>N: GET /servers/{id}
      N-->>S: status
    end
    alt status ACTIVE
      S-->>U: table, exit 0
    else status ERROR
      S-->>U: Error creating server, exit 1
    end
  end

Diagnostics: without --wait, success only means that Nova accepted the request; read fault in server show. A failure before POST /servers is local or a lookup: the server was not created.

Sources: openstackclient/compute/v2/server.py:1634, openstackclient/compute/v2/server.py:2257, openstackclient/compute/v2/server.py:2265, osc-lib:osc_lib/utils/__init__.py:779.

4. Deleting several resources

sequenceDiagram
  autonumber
  actor U as User
  participant S as openstack
  participant N as Nova
  U->>S: server delete a b
  loop each name
    S->>N: GET /servers/{name}, then GET /servers/detail?name=
    alt found
      S->>N: DELETE /servers/{id} (static)
    else not found
      S-->>U: Failed to delete server with name or ID ...
    end
  end
  alt at least one failure
    S-->>U: n of m servers failed to delete, exit 1
  else
    S-->>U: exit 0, no output
  end

Diagnostics: exit 1 does not mean that nothing was deleted. Read the per-target lines.

Source: openstackclient/compute/v2/server.py:2309.

5. Uploading an object

Swift does not go through the SDK: no discovery, no microversion.

sequenceDiagram
  autonumber
  actor U as User
  participant S as openstack
  participant KS as Keystone
  participant O as Swift
  U->>S: object create c f
  S->>KS: POST /v3/auth/tokens
  S->>S: open the local file
  alt missing file
    S-->>U: No such file or directory, exit 1
  else
    S->>O: PUT /AUTH_p/c/f (streamed, static)
    O-->>S: 201, Etag, X-Trans-Id
    S-->>U: table with account, container, object, etag
  end

Diagnostics: the object is named after the local path unless --name is given (openstackclient/api/object_store_v1.py:253). etag and x-trans-id are the values to look up in Swift's logs.

Source: openstackclient/object/v1/object.py:82.

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