python-manilaclient — Interactions

Interactions — python-manilaclient — branch stable/2026.2

Branch stable/2026.2 @ d18a7e966 (6.3.0 + 2 maintenance commits) — repository https://opendev.org/openstack/python-manilaclient — analysed on 2026-11-01

There is no database, message bus or cache. The only network peers are Keystone, Manila and, for a few options, Neutron. Everything marked [observed] was seen against the local stub, which is not Manila.

1. Client stack

flowchart LR
  cmd[manilaclient/osc/v2 command] --> mgr[manilaclient/v2 manager]
  mgr --> sc[httpclient.SessionClient]
  sc --> ksa[keystoneauth1 session]
  ksa -->|HTTPS + X-Auth-Token| manila[Manila]
  ksa -->|password or other auth plugin| ks[Keystone]
  cmd -->|identity_client| ksc[python-keystoneclient]
  ksc --> ksa
  cmd -->|client_manager.network| sdk[openstacksdk]
  sdk --> ksa
  ksa -->|find network and subnet| neutron[Neutron]

• Commands call share_client.<manager>.<method> and methods of Resource objects (manilaclient/osc/v2/share.py:1712).
• Managers build URLs and bodies. Each microversion variant is a separate function chosen by api_versions.wraps (manilaclient/api_versions.py:420).
• **SessionClient** is a keystoneauth LegacyJsonAdapter. It keeps the microversion as default_microversion, and turns any status >= 400 into a manilaclient exception (manilaclient/common/httpclient.py:65, manilaclient/common/httpclient.py:97-99).
• **HTTPClient** is a second, requests-based client, created only when a caller passes input_auth_token (manilaclient/v2/client.py:169-189). make_client never does (manilaclient/osc/plugin.py:85-96), so no OSC command uses it. It matters only to Python API users.

2. Keystone

Those lookups use python-keystoneclient, not the SDK. Two helpers behave differently when Keystone refuses them [observed, cases quota-show-forbidden and list-project-forbidden]:

So a user who cannot read Keystone projects cannot run share quota show, even for their own project, unless Keystone allows the lookup [inferred from the stub's 403; Keystone's real policy was not exercised].

3. Catalog and endpoint

Discovery uses the path of the endpoint. _get_base_url cuts the URL before /vN (manilaclient/common/httpclient.py:70-83). A catalog URL without /vN gives the root of the host: with --os-endpoint-override http://host/somewhere, discovery goes to GET http://host/, while requests go to /somewhere/shares/detail [observed, case override-unversioned]. A deployment behind a path prefix must keep /v2 in the URL.

4. Microversion negotiation

Every command that touches client_manager.share runs this once [observed: one discovery request per command, on all 154].

flowchart TD
  a[Requested: --os-share-api-version, OS_SHARE_API_VERSION, or 2.98] --> b[GET base URL, sent at 2.98]
  b --> c{entry with status CURRENT and a non-empty version}
  c -- no --> d[version 1.0, then refused: not in API_VERSIONS]
  c -- yes --> e{requested within min..max}
  e -- yes --> f[use requested]
  e -- requested above max --> g[use server max, debug log only]
  e -- requested below min --> h[UnsupportedVersion]

Headers

Every request to Manila carries these [observed, case headers-sample]:

X-Auth-Token: <token>
User-Agent: python-manilaclient
Accept: application/json
OpenStack-API-Version: shared-file-system 2.98
X-OpenStack-Manila-API-Version: 2.98

Manila reads only X-OpenStack-Manila-API-Version (manila:manila/api/openstack/wsgi.py:53, manila:manila/api/openstack/wsgi.py:226). keystoneauth adds both (keystoneauth:keystoneauth1/session.py:730, manilaclient/common/httpclient.py:65).

Experimental header

X-OpenStack-Manila-API-Experimental: true is set by experimental_api (manilaclient/api_versions.py:404-417) on the client object, so it stays on every later request of that process [observed: share backup create sends the GET of the share without it, and the POST with it]. It is sent:

A service must accept the header on any route, and must answer experimental routes when it is present (manila:manila/api/openstack/wsgi.py:245-248).

5. Manila REST calls

The complete list is generated: [_rewrite/api-surface_stable-2026.2.md](_rewrite/api-surface_stable-2026.2.md), with the microversion range of each route, and [_rewrite/manager-routes_stable-2026.2.json](_rewrite/manager-routes_stable-2026.2.json), per manager method and variant. Conventions that hold across them:

Name lookup is expensive

apiutils.find_resource tries, in order, an integer ID, a UUID, then find(human_id=…) and find(name=…) (manilaclient/common/apiclient/utils.py:39-69). find lists the whole collection with all_tenants=1 and filters on the client (manilaclient/base.py:253-279). From 2.69, shares are listed a second time with is_soft_deleted=True (manilaclient/base.py:264-269).

So share show <name> sends four listings before the show [observed, case name-lookup]:

GET /shares/detail?all_tenants=1&is_public=True
GET /shares/detail?all_tenants=1&is_public=True&is_soft_deleted=True
GET /shares/detail?all_tenants=1&is_public=True
GET /shares/detail?all_tenants=1&is_public=True&is_soft_deleted=True
GET /shares/{id}/export_locations

osc_lib.utils.find_resource, used by the newer commands, tries GET /<resource>/{name} first (osc-lib:osc_lib/utils/__init__.py:234), then find. Both forms exist in the plugin, and the choice is per command (manilaclient/osc/v2/share.py:807, manilaclient/osc/v2/share_backups.py:300).

6. Neutron

7. Other

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