OpenKeel: the sovereign French Cloud solution of the inherent group, with a European reach Discover inherent

Get started

Reverse-spec · Clients

python-manilaclient — Scenarios

End-to-end scenarios — 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

The client side of each scenario was run against the local stub [observed]. The Manila side is shown only where the client depends on it, and it was not run: what happens on a real service is [inferred] from reverse-spec-manila.

1. Any command: authentication and negotiation

sequenceDiagram
  autonumber
  actor U as Operator
  participant C as openstack + plugin
  participant K as Keystone
  participant M as Manila
  U->>C: openstack share list
  C->>C: load entry points, group openstack.share.v2
  C->>K: POST /v3/auth/tokens, token and catalog
  C->>C: endpoint for shared-file-system, then sharev2
  C->>M: GET base URL (cut before /vN), X-OpenStack-Manila-API-Version 2.98
  alt versions[] has a CURRENT entry
    M-->>C: 200, version and min_version
    Note over C: requested 2.98 kept, or lowered to the server maximum
  else no entry or no versions key
    M-->>C: 200
    C-->>U: Invalid share client version '1.0', exit 1
  else 404
    M-->>C: 404
    C-->>U: the 404 message, exit 1
  end
  C->>M: GET /shares/detail, 2.98
  M-->>C: 200 {"shares": [...]}
  C-->>U: table

Source: manilaclient/osc/plugin.py:63-120, manilaclient/api_versions.py:244-293. Cases: disc-*, catalog-*, override-*.

Diagnostics: --debug shows both requests. If a command fails with Invalid share client version '1.0', look at the answer of the base URL, and at whether the catalog URL has /v2 in its path (manilaclient/common/httpclient.py:70-83). One discovery request is added to each command, so scripts pay for it on every call.

2. Create a share and wait

sequenceDiagram
  autonumber
  actor U as Operator
  participant C as share create
  participant M as Manila API
  participant S as Manila scheduler and share service
  U->>C: share create NFS 1 --wait
  C->>M: GET /types/default
  alt no default type
    M-->>C: 404
    C-->>U: the 404 message, exit 1 (defect 14)
  else
    M-->>C: {"share_type": {"id": ...}}
  end
  C->>M: POST /shares {"share": {...}}
  M-->>C: {"share": {"id": ..., "status": "creating"}}
  M-)S: asynchronous create (inferred)
  loop every 5 s, no limit
    C->>M: GET /shares/{id}
    M-->>C: status
  end
  alt available
    C->>M: GET /shares/{id}
    C-->>U: details, exit 0
  else error
    C-->>U: ERROR: Share is in error state. details, exit 0 (defect 17)
  end

Source: manilaclient/osc/v2/share.py:226-359, manilaclient/v2/shares.py:185-208. Body seen [observed]:

{"share": {"size": 1, "snapshot_id": null, "name": null, "description": null, "metadata": {},
           "share_proto": "NFS", "share_network_id": null, "share_type": "{id}", "is_public": false,
           "availability_zone": null, "scheduler_hints": {}}}

Diagnostics: exit 0 with --wait does not prove that the share is available; read the status field or stderr. Without --wait, the display is the state just after the POST. Then share message list --resource-id <id> explains a failure on the service side.

3. Find a resource by name

sequenceDiagram
  autonumber
  participant C as share show myshare
  participant M as Manila
  Note over C: not an integer, not a UUID
  C->>M: GET /shares/detail?all_tenants=1&is_public=True
  C->>M: GET /shares/detail?all_tenants=1&is_public=True&is_soft_deleted=True
  Note over C: find(human_id): no match, human_id is None
  C->>M: GET /shares/detail?all_tenants=1&is_public=True
  C->>M: GET /shares/detail?all_tenants=1&is_public=True&is_soft_deleted=True
  alt one match
    C->>M: GET /shares/{id}/export_locations
  else none
    C-->>C: No share with a name or ID of 'myshare' exists.
  else several
    C-->>C: Multiple share matches found for 'myshare', use an ID to be more specific.
  end

Source: manilaclient/common/apiclient/utils.py:21-79, manilaclient/base.py:237-279. Case: name-lookup.

Diagnostics: name lookups load every share visible to the user, four times, from 2.69. On a large cloud, use IDs in scripts. The filter works on the client, so a slow share show with a name is not a slow show on the server.

4. Change a share: share set

sequenceDiagram
  autonumber
  participant C as share set S --name y
  participant M as Manila
  C->>M: GET /shares/{id}
  C->>M: PUT /shares/{id} {"share": {"display_name": "y"}}
  M-->>C: 200
  C->>M: POST /shares/{id}/action {"reset_task_state": {"task_state": null}}
  alt admin
    M-->>C: 202, task state cleared (inferred)
    C-->>C: exit 0
  else member
    M-->>C: 403 (inferred from the policy)
    C-->>C: Failed to update share task state, then One or more of the set operations failed, exit 1
  end

Source: manilaclient/osc/v2/share.py:913-971. Cases: set-task-state, set-task-state-forbidden. See defect 1 in 02 § 4.

Diagnostics: if share set exits 1 although the change is visible, this is the cause. Python API users call share.update directly and are not affected.

5. Grant access, then wait

sequenceDiagram
  autonumber
  participant C as share access create S ip 10.0.0.1 --wait
  participant M as Manila
  C->>M: GET /shares/{id}
  Note over C: local validation of the rule, by type and version
  C->>M: POST /shares/{id}/action {"allow_access": {"access_type": "ip", "access_to": "10.0.0.1"}}
  M-->>C: {"access": {"id": ...}}
  loop every 5 s, no limit
    C->>M: GET /share-access-rules/{id}
    M-->>C: {"access": {"state": ...}}
  end
  C->>M: GET /share-access-rules/{id}
  C-->>C: table, properties from metadata

Source: manilaclient/osc/v2/share_access_rules.py:126-199, manilaclient/v2/shares.py:902-933. Below 2.45 the wait fails, after the rule was created (defect 12).

Diagnostics: error on the rule logs ERROR: Share access rule is in error state., and the command exits 0. A wrong address fails before any POST, with the error text of Python's ipaddress.

6. Migrate a share

sequenceDiagram
  autonumber
  participant C as share migration ...
  participant M as Manila
  C->>M: GET /shares/{id} (or name lookup)
  C->>M: POST /shares/{id}/action {"migration_start": {"host": ..., "writable": "True", ...}}
  Note over C: below 2.96, header X-OpenStack-Manila-API-Experimental true
  loop operator polls
    alt 2.98 and above
      C->>M: GET /shares/{id}/migration-progress
    else below 2.98
      C->>M: POST /shares/{id}/action {"migration_get_progress": null}
    end
    M-->>C: total_progress, task_state
  end
  C->>M: POST /shares/{id}/action {"migration_complete": null}

Source: manilaclient/osc/v2/share.py:1698-1793, manilaclient/v2/shares.py:215-386. Both share migration start and complete return nothing on success.

Diagnostics: start returning without error says only that the request was accepted. Do not run share set during a migration as an admin: it clears the task state (defect 1, [inferred]).

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