python-barbicanclient — Cli commands

CLI commands — python-barbicanclient — branch stable/2026.2

Branch stable/2026.2 @ 8162006e8677 — repository https://opendev.org/openstack/python-barbicanclient — analysed on 2026-11-01

python-barbicanclient exposes no API of its own. Its interface is 23 commands, loaded in openstack as a plugin and in the deprecated barbican shell, and the Python library under them. Its contract with the outside is the REST calls it sends to Barbican (03, 07).

"Requests" below were observed on a local stub. That shows the routes and bodies the client sends, not what a real Barbican does with them.

1. Shared mechanics

• Plugin loading: the entry point openstack.cli.extension: key_manager = barbicanclient.osc_plugin (setup.cfg:33) names the module. OSC reads API_NAME, API_VERSIONS, API_VERSION_OPTION and build_option_parser (barbicanclient/osc_plugin.py:18), adds the global --os-key-manager-api-version (default 1, env OS_KEY_MANAGER_API_VERSION, barbicanclient/osc_plugin.py:35), and adds the group openstack.key_manager.v1 (openstackclient:openstackclient/shell.py:135).
• Client creation: lazily, at the first access to client_manager.key_manager (osc-lib:osc_lib/clientmanager.py:36, openstackclient:openstackclient/common/clientmanager.py:251), through make_client (barbicanclient/osc_plugin.py:26). Creation sends the two discovery requests. So a command that fails argument checks after touching the client has already done authentication and discovery [observed: secret container create without --secret sends discovery, then fails].
• Microversion: negotiated per process, 1.2 at most; the user cannot choose it from the CLI. See 03 § 2.
• Reference arguments: URI accepts a full URL or a bare UUID, except on acl *, which need a URL. Only the last path segment is used, parsed as a UUID (barbicanclient/base.py:37). The host part is ignored [observed]. Non-canonical UUID forms are accepted, since uuid.UUID parses them (barbicanclient/base.py:46).
• Output: cliff's ShowOne and Lister give the options -f table|json|yaml|csv|value, -c. command.Command prints nothing. Fields are formatted by the EntityFormatter mixins (barbicanclient/formatter.py:16).
• Immutable after save: entity objects refuse setters once they have a ref (barbicanclient/v1/secrets.py:38, barbicanclient/v1/orders.py:28, barbicanclient/v1/containers.py:29). This applies to the Python API; no command sets a property after creation.
• Exit codes: 0 success, 1 any exception, 2 usage error or unknown command; see 02.

2. Functional description by family

Secrets (secret store|get|list|update|delete)

Purpose: keep a sensitive value (key, passphrase, certificate) in Barbican. Actor: any project member the service's policy allows; the client knows nothing of policy.

• store (barbicanclient/barbican_cli/v1/secrets.py:151). Creates a secret, with or without payload.
  • Defaults sent every time: algorithm=aes, bit_length=256, mode=cbc, secret_type=opaque (barbicanclient/barbican_cli/v1/secrets.py:158, barbicanclient/barbican_cli/v1/secrets.py:170) [observed].
  • The payload is encoded by these rules (barbicanclient/v1/secrets.py:338): | Input | payload sent | payload_content_type | payload_content_encoding | Source | |---|---|---|---|---| | --payload x, no -t, no -e | base64 of the UTF-8 bytes | application/octet-stream | base64 | barbicanclient/barbican_cli/v1/secrets.py:196, barbicanclient/v1/secrets.py:370 | | --file f, no -t, no -e | base64 of the file | application/octet-stream | base64 | barbicanclient/v1/secrets.py:370 | | --payload x with -t or -e | the text, unchanged | as given | as given | barbicanclient/v1/secrets.py:355 | | --file f with -t or -e | the file decoded as UTF-8; fails on anything else | as given | as given | barbicanclient/v1/secrets.py:363 | | no payload, -t given | none, only payload_content_type | as given | | barbicanclient/v1/secrets.py:366 | | --payload "" | none: treated as absent | | | barbicanclient/barbican_cli/v1/secrets.py:196 | | empty --file | refused: Invalid Payload: Cannot Be Empty String | | | barbicanclient/v1/secrets.py:351 |
  • All cases above were [observed]. The str branch at barbicanclient/v1/secrets.py:380 (text/plain) is unreachable from the CLI, because the command always encodes first.
  • Outcome: the table shows the secret_ref returned. With --name, no reload happens, and Created, Status, Content types print None. Without a name the client reloads, about 10 times [observed]; see 02 § 4.
• get (barbicanclient/barbican_cli/v1/secrets.py:43).
  • Without options: metadata from GET /secrets/{id}.
  • With --decrypt, --payload or --file (mutually exclusive): GET /secrets/{id}/payload with Accept from -t/--payload_content_type, default text/plain. A text/plain answer is decoded as UTF-8 (barbicanclient/v1/secrets.py:324). The service translates between stored and requested type, and answers 406 when the bytes are not valid UTF-8 for text (barbican:barbican/plugin/util/translations.py:103).
  • --file refuses an existing file, after fetching, and prints nothing on success (barbicanclient/barbican_cli/v1/secrets.py:78) [observed].
• list (barbicanclient/barbican_cli/v1/secrets.py:111). One page, default 10. Filters --name, --algorithm (alg), --bit-length (bits), --mode, --secret-type [observed]. Time filters and sort exist only in the Python API (barbicanclient/v1/secrets.py:667).
• update (barbicanclient/barbican_cli/v1/secrets.py:96). Adds a payload to a secret stored without one: PUT /secrets/{id}, Content-Type: text/plain. The payload is a positional argument, hence visible in the process list. The service refuses a secret that already has data (barbican:barbican/api/controllers/secrets.py:58).
• delete (barbicanclient/barbican_cli/v1/secrets.py:25). Behaviour depends on the microversion; see 03 § 2 and 04 § 5.

Secret consumers (secret consumer create|delete|list)

Purpose: declare which service and resource use a secret, so that deleting it is refused at 1.2 and above. All need microversion 1.1 (barbicanclient/v1/secrets.py:683). Required: --service-type-name, --resource-type, --resource-id.

• create (barbicanclient/barbican_cli/v1/secrets.py:209): POST /secrets/{id}/consumers/. The returned secret is read into a Secret, then dropped: nothing is printed (barbicanclient/v1/secrets.py:717).
• delete (barbicanclient/barbican_cli/v1/secrets.py:233): DELETE /secrets/{id}/consumers with the same JSON body.
• list (barbicanclient/barbican_cli/v1/secrets.py:257): GET /secrets/{id}/consumers?limit&offset; columns Service, Resource type, Resource id, Created.

Orders (secret order create|get|list|delete)

Purpose: ask the service to generate key material. The order is processed asynchronously by the service; the client does not wait (05).

• create (barbicanclient/barbican_cli/v1/orders.py:21): positional type, key or asymmetric. Defaults aes, 256, cbc, application/octet-stream, whatever the type [observed]. For asymmetric, --mode is accepted and ignored (barbicanclient/v1/orders.py:272) [observed], and the passphrase of the Python API has no option. Prints the order with Status None [observed].
• get (barbicanclient/barbican_cli/v1/orders.py:73): builds a KeyOrder or AsymmetricOrder from type (barbicanclient/v1/orders.py:343).
• list (barbicanclient/barbican_cli/v1/orders.py:87), delete (barbicanclient/barbican_cli/v1/orders.py:61).

A key order must have only name, algorithm, mode, bit_length, expiration, payload_content_type in meta (barbicanclient/v1/orders.py:226, barbicanclient/v1/orders.py:348).

Containers (secret container create|get|list|delete)

Purpose: group secret references: generic, rsa (public_key, private_key, private_key_passphrase), certificate (certificate, intermediates, private_key, private_key_passphrase).

• create (barbicanclient/barbican_cli/v1/containers.py:79):
  • --secret name=ref repeated. No --secret at all is refused (barbicanclient/barbican_cli/v1/containers.py:135). A value without exactly one = is silently dropped (barbicanclient/barbican_cli/v1/containers.py:138) [observed].
  • Each ref is parsed as a UUID locally; failure gives One or more of the provided secret_refs could not be retrieved! (barbicanclient/v1/containers.py:103) [observed]. The client does not check that the secret exists.
  • For typed containers, only the expected names are kept, and others dropped silently (barbicanclient/barbican_cli/v1/containers.py:103). Required names are not checked locally: an empty rsa is sent [observed], and the service validates (barbican:barbican/common/validators.py:732).
  • Secret names are lower-cased (barbicanclient/v1/containers.py:116).
  • After the POST, the client reads status, which sends GET /containers/{id} [observed].
• get (barbicanclient/barbican_cli/v1/containers.py:37): the columns depend on the type (barbicanclient/v1/containers.py:40, barbicanclient/v1/containers.py:268, barbicanclient/v1/containers.py:385).
• list (barbicanclient/barbican_cli/v1/containers.py:51): generic columns for every type (barbicanclient/v1/containers.py:265). Filters --name, --type.
• delete (barbicanclient/barbican_cli/v1/containers.py:25).

The client has no command for container consumers; see § 4.

ACLs (acl get|submit|delete, acl user add|remove)

Purpose: grant read access on a secret or container to given users, and enable or disable project-wide access. Only the read operation exists on the CLI (barbicanclient/barbican_cli/v1/acls.py:49).

The URI decides the type: a path element secrets or containers is required, so a bare UUID is refused (barbicanclient/v1/acls.py:412) [observed]. A URI containing /acl anywhere is refused too (barbicanclient/v1/acls.py:373) [observed].

• get (barbicanclient/barbican_cli/v1/acls.py:103): GET …/acl.
• submit (barbicanclient/barbican_cli/v1/acls.py:131): replaces the ACL: PUT …/acl, then GET. Without --user it sends {"read": {"users": []}}, which clears the users [observed] (barbicanclient/v1/acls.py:295).
• delete (barbicanclient/barbican_cli/v1/acls.py:84): DELETE …/acl.
• user add (barbicanclient/barbican_cli/v1/acls.py:161) and user remove (barbicanclient/barbican_cli/v1/acls.py:212): read-modify-write: GET, change locally, PUT, GET [observed]. No lock, no generation: a concurrent change is lost [inferred]. user add does not remove duplicates (barbicanclient/barbican_cli/v1/acls.py:199) [observed]. user remove loses the order of users (barbicanclient/barbican_cli/v1/acls.py:254).

The column list has 6 entries for 6 values because the command copies columns from the parent onto each entry (barbicanclient/barbican_cli/v1/acls.py:78). ACLFormatter.columns alone has 5 (barbicanclient/v1/acls.py:34).

Certificate authorities (ca get|list)

ca get (barbicanclient/barbican_cli/v1/cas.py:22) and ca list (barbicanclient/barbican_cli/v1/cas.py:35) read /cas. ca list issues one more GET /cas/{id} per CA, since the list holds refs only (barbicanclient/v1/cas.py:239) [observed].

**Barbican stable/2026.2 has no such route** (barbican:barbican/api/controllers/versions.py:141), so both should end in a 404 there [inferred]. They are kept for older services.

3. Commands

"Exit" is that of the base run with synthetic arguments, against the stub answering 404, {}, and bodies shaped from the Barbican source. Requests cover all option variants in all modes. Machine-readable versions: cli-commands, client-contract.

The base secret container create exits 1 in all modes because it has no --secret: the parser accepts that, and the command refuses it. Its 3 variants exit 0 in 200 and shape.

4. Python API behind the commands

barbicanclient.secrets and similar old import paths still work with a warning (barbicanclient/__init__.py:44).

CreateContainer bypasses the manager and instantiates container classes with client.containers._api, a private attribute (barbicanclient/barbican_cli/v1/containers.py:106).

5. Legacy barbican shell (separate process)

barbican (setup.cfg:30, barbicanclient/barbican.py:46) is a cliff application that loads the same openstack.key_manager.v1 group (barbicanclient/barbican.py:69) plus help and complete. It prints a deprecation warning saying it "will be removed in the O release" on each start (barbicanclient/barbican.py:382) [observed].

Other differences with the plugin: it has no clouds.yaml, reads BARBICAN_* variables (barbicanclient/barbican.py:309), and accepts --barbican-api-version, where any value but v1 gives Invalid client version v2; must be one of: v1 [observed]. help and complete need no authentication (barbicanclient/barbican.py:63). Its defects are in 02 § 4. doc/source/cli/details.rst:26 still documents version 4.3.0.

6. Arguments of each command

The options of cliff formatters are left out. Full data is in cli-commands.

**acl delete**

**acl get**

**acl submit**

**acl user add**

**acl user remove**

**ca get**

**ca list**

**secret consumer create**

**secret consumer delete**

**secret consumer list**

**secret container create**

**secret container delete**

**secret container get**

**secret container list**

**secret delete**

**secret get**

**secret list**

**secret order create**

**secret order delete**

**secret order get**

**secret order list**

**secret store**

**secret update**

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