python-octaviaclient — Cli commands

CLI commands — python-octaviaclient — branch stable/2026.2

Branch stable/2026.2 @ b37975ec8f2d (tag 3.15.0 + 2 commits) — repository https://opendev.org/openstack/python-octaviaclient — analysed on 2026-11-01

python-octaviaclient exposes no API of its own. It is a plugin of the openstack command, turning 82 commands into calls to the Octavia REST API. Its contract with the outside world is the requests it sends (03, 07). [observed] means seen against the local stub; a stub says nothing about a real service.

1. Shared mechanics

Plugin loading

• openstack.cli.extension = load_balancer names the plugin module, and openstack.load_balancer.v2 lists one class per command (setup.cfg:29-33).
• make_client builds one OctaviaAPI from the session and the catalog endpoint of type load-balancer, with the region and interface of the CLI (octaviaclient/osc/plugin.py:30-42). It sets no timeout.
• --os-loadbalancer-api-version (env OS_LOADBALANCER_API_VERSION, default 2.0) is added by octaviaclient/osc/plugin.py:55-63. It only chooses the command group: OSC uses the major part to build openstack.load_balancer.v<major> (openstackclient:openstackclient/shell.py:150-156).
  • 3 makes every command disappear: 'loadbalancer list' is not an openstack command, exit 2 [observed].
  • 2.99 changes nothing and warns about nothing, because OSC looks for API_VERSIONS (openstackclient:openstackclient/shell.py:119) while the plugin names it LOAD_BALANCER_API_VERSIONS (octaviaclient/osc/plugin.py:25) [observed].
  • The value is never sent to the service.

The API layer

OctaviaAPI (octaviaclient/api/v2/octavia.py:65) has 73 public methods, one per route. All are wrapped by correct_return_codes (octaviaclient/api/v2/octavia.py:26), see 02 § 2. Four private helpers do the work:

Name to ID resolution

Almost every command accepts a name or an ID. Attribute maps (octaviaclient/osc/v2/utils.py:252-722) say how each option becomes a body field or a query parameter: a 2-tuple applies a function, a 3-tuple resolves a resource, a 4-tuple resolves a child through its parent (octaviaclient/osc/v2/utils.py:27-65).

_find_resource (octaviaclient/osc/v2/utils.py:68-105):

1. if the value looks like a UUID, list with ?id=<value>; availability zones skip this step (octaviaclient/osc/v2/utils.py:110);
2. if nothing came back, list with ?name=<value>;
3. more than one match gives <n> <resource> found with name or ID of <value>. Please try again with UUID (octaviaclient/osc/v2/utils.py:137-140);
4. no match gives Unable to locate <value> in <resource> (octaviaclient/osc/v2/utils.py:101-103).

Special cases:

• Projects go through identity_common.find_project (octaviaclient/osc/v2/utils.py:172-179), that is GET /v3/projects/<value>, then GET /v3/projects?name=<value> [observed]. The literal value non-uuid skips the lookup and is sent as is (octaviaclient/osc/v2/utils.py:173) [observed].
• Network resources go through openstacksdk (octaviaclient/osc/v2/utils.py:125-128).
• **none, null, void** on --vip-qos-policy-id mean JSON null (octaviaclient/osc/v2/utils.py:162-164), and likewise on the TLS references of listeners and pools (octaviaclient/osc/v2/utils.py:768-771).
• Parents are resolved twice for members and rules: once for the pool or l7policy key, once for the child (octaviaclient/osc/v2/utils.py:52-64), hence two identical list calls [observed].

show commands try the direct route first when the value looks like a UUID, and fall back on the lookup on osc-lib NotFound (for example octaviaclient/osc/v2/load_balancer.py:389-403). A name goes straight to the lookup and then to the direct route, so a name costs two requests and a missing UUID three [observed].

Command shapes

set with no option still sends PUT {"<wrapper>": {}} [observed]. unset with only --wait sends nothing and exits 0 [observed].

Tags

• --tag on create is sent as given; --no-tag on create has no effect, since the map reads only tags (octaviaclient/osc/v2/utils.py:200-207) [observed].
• set --tag reads the resource, merges, and sends the whole set (octaviaclient/osc/v2/utils.py:824-829). set --no-tag sends []. unset --tag reads and subtracts; unset --all-tag sends [] (octaviaclient/osc/v2/utils.py:834-841). The read-modify-write has no retry, and the order of the list depends on Python's set order [observed].
• List filters --tags, --any-tags, --not-tags, --not-any-tags become repeated query parameters tags, tags-any, not-tags, not-tags-any (octaviaclient/osc/v2/utils.py:200-207) [observed].
• Filters use --tags and --any-tags, as defined in osc-lib:osc_lib/utils/tags.py:33.

--wait

See 05. What is polled depends on the command:

2. Functional description by family

Load balancers (loadbalancer create|list|show|set|unset|delete|failover|stats show|status show)

• create (octaviaclient/osc/v2/load_balancer.py:34). Purpose: ask for a new load balancer. The attribute map is applied first, so lookups run before local checks. At least one of --vip-subnet-id, --vip-network-id, --vip-port-id is required, and --vip-network-id cannot go with --vip-port-id (octaviaclient/osc/v2/load_balancer.py:38-47). --enable defaults to true, so admin_state_up: true is always sent. Options:
  • --additional-vip subnet-id=<x>[,ip-address=<ip>] (repeatable): the subnet is resolved and the address checked with ipaddress (octaviaclient/osc/v2/utils.py:210-239);
  • --vip-sg-id (repeatable): each security group is resolved (octaviaclient/osc/v2/utils.py:242-249);
  • a missing vip_vnic_type in the response is displayed as normal (octaviaclient/osc/v2/load_balancer.py:178). Outcome: the service answers while the load balancer is PENDING_CREATE; without --wait the command prints that state [inferred from the Octavia API; the stub always answers ACTIVE].
• delete (octaviaclient/osc/v2/load_balancer.py:193): --cascade adds ?cascade=True (octaviaclient/osc/v2/utils.py:293) [observed]. Without it, a service may refuse a load balancer with children: octavia:octavia/api/v2/controllers/load_balancer.py:890.
• failover (octaviaclient/osc/v2/load_balancer.py:235): PUT …/failover with no body.
• stats show reads stats (octaviaclient/osc/v2/load_balancer.py:591). status show prints the statuses tree as JSON itself, with no cliff formatter, and prints {} if the key is absent (octaviaclient/osc/v2/load_balancer.py:617-618) [observed].

Listeners (octaviaclient/osc/v2/listener.py, attribute map octaviaclient/osc/v2/utils.py:322-376)

• create (octaviaclient/osc/v2/listener.py:34) checks the port range and that --hsts-max-age accompanies the other HSTS options (octaviaclient/osc/v2/validate.py:59-69). set (octaviaclient/osc/v2/listener.py:593) performs no such check.
• --insert-headers k=v,k=v becomes an object of strings (octaviaclient/osc/v2/utils.py:758-765). --connection-limit is sent as a string on create and set [observed], and set does not even require an integer (octaviaclient/osc/v2/listener.py:426).
• --allowed-cidr, --tls-version, --alpn-protocol repeat; --sni-container-refs takes several values on one option (octaviaclient/osc/v2/listener.py:84-86).

Pools (octaviaclient/osc/v2/pool.py, attribute map octaviaclient/osc/v2/utils.py:379-426)

--listener or --loadbalancer chooses the parent; --session-persistence type=…,cookie_name=… becomes an object of strings, so numeric values stay strings (octaviaclient/osc/v2/utils.py:405). --enable-tls and --disable-tls map to tls_enabled (octaviaclient/osc/v2/utils.py:415-416).

Members (octaviaclient/osc/v2/member.py, attribute map octaviaclient/osc/v2/utils.py:429-470)

Each command needs the pool. --protocol-port and --weight are checked locally (octaviaclient/osc/v2/validate.py:72-88). --monitor-port is not, see 02 § 5. A missing vnic_type is displayed as normal (octaviaclient/osc/v2/member.py:103-104). The batch PUT /pools/{id}/members of Octavia is not used.

L7 policies and rules (octaviaclient/osc/v2/l7policy.py, octaviaclient/osc/v2/l7rule.py)

• A redirect action needs its target: --redirect-pool, --redirect-url or --redirect-prefix (octaviaclient/osc/v2/validate.py:19-33). REJECT needs none.
• A rule of type COOKIE or HEADER needs --key (octaviaclient/osc/v2/validate.py:36-43).
• The wrapper of a rule is rule, and its collection key is rules (octaviaclient/osc/v2/l7rule.py:111, octaviaclient/api/constants.py:20).
• l7rule unset takes the rule's ID as given, with no lookup (octaviaclient/osc/v2/l7rule.py:400), unlike show, set and delete.

Health monitors (octaviaclient/osc/v2/health_monitor.py, attribute map octaviaclient/osc/v2/utils.py:548-584)

--delay and --timeout have no parser type and are converted by int() in the map, so a non-integer gives a raw Python message (octaviaclient/osc/v2/health_monitor.py:54, octaviaclient/osc/v2/utils.py:566) [observed]. --http-version is a float from 1.0 or 1.1.

Quotas (octaviaclient/osc/v2/quota.py)

• set (octaviaclient/osc/v2/quota.py:98) needs at least one limit (octaviaclient/osc/v2/quota.py:102-110), and sends load_balancer and health_monitor [observed]. unset (octaviaclient/osc/v2/quota.py:213) sends loadbalancer and healthmonitor [observed], because it uses the option names as keys (octaviaclient/osc/v2/utils.py:779-780). Octavia accepts both spellings and calls the first one misspelled and deprecated (octavia:octavia/api/v2/types/quotas.py:63).
• list uses the listener map only for its project key (octaviaclient/osc/v2/quota.py:45).
• defaults show calls GET /lbaas/quotas/defaults (octaviaclient/api/constants.py:61), not Octavia's /{project_id}/default.
• reset is DELETE /lbaas/quotas/{id}.

Amphorae (octaviaclient/osc/v2/amphora.py, admin operations)

Routes are under /octavia/amphorae. show, delete and stats show use the ID as given; configure and failover look it up through the list, by ?id= or ?name= (octaviaclient/osc/v2/utils.py:611-615). failover reads the amphora before acting, to know its load balancer (octaviaclient/osc/v2/amphora.py:194). stats show adds up every row, or the rows of one listener with --listener (octaviaclient/osc/v2/amphora.py:248-256).

Providers, flavors, availability zones

• **provider capability list** calls the flavor route, the availability zone route, or both; --flavor and --availability-zone are mutually exclusive (octaviaclient/osc/v2/provider.py:71-99). The provider name goes in the path unencoded.
• **flavor and flavorprofile** (octaviaclient/osc/v2/flavor.py, octaviaclient/osc/v2/flavorprofile.py): --flavor-data is sent as a JSON string, not an object (octaviaclient/osc/v2/utils.py:674).
• **availabilityzone and availabilityzoneprofile**: an availability zone has no id; its name is the key (octaviaclient/osc/v2/utils.py:168-169). --availability-zone-data is a JSON string (octaviaclient/osc/v2/utils.py:716).

Lifecycle as the client sees it

The client never drives status itself; it reads provisioning_status (status for amphorae, octaviaclient/osc/v2/amphora.py:289).

stateDiagram-v2
  [*] --> PENDING: POST or PUT or DELETE sent, service answers
  PENDING --> ACTIVE: --wait ends with exit 0
  PENDING --> ERROR: --wait ends with exit 1, message "did not successfully reach ACTIVE status"
  PENDING --> Gone: delete --wait, GET answers 404, exit 0
  PENDING --> ERROR: delete --wait, exit 1, message "could not be successfully deleted"
  Gone --> [*]

3. The 82 commands

Requests below come from the typed stub with required arguments only, and show the whole sequence of service requests [observed]. Keystone calls are left out. Each row of loadbalancer … unset shows nothing because the command sends nothing without an option; see § 4. [network] and [identity] mark Neutron and Keystone requests.

amphora (6 commands)

availabilityzone (6 commands)

availabilityzoneprofile (5 commands)

flavor (6 commands)

flavorprofile (5 commands)

healthmonitor (6 commands)

l7policy (6 commands)

l7rule (6 commands)

listener (7 commands)

loadbalancer (9 commands)

member (6 commands)

pool (6 commands)

provider (2 commands)

quota (6 commands)

4. Effect of each option on the wire

Generated from _rewrite/wire-probe-options_stable-2026.2.json [observed on the stub]. Each row compares the command with the same command without the option. Commands with no option are left out. extra marks a request that exists only with the option, usually a lookup; ?name or ?id shows its query key.

amphora

**loadbalancer amphora configure** (octaviaclient/osc/v2/amphora.py:132)

**loadbalancer amphora delete** (octaviaclient/osc/v2/amphora.py:262)

**loadbalancer amphora failover** (octaviaclient/osc/v2/amphora.py:171)

**loadbalancer amphora list** (octaviaclient/osc/v2/amphora.py:25)

**loadbalancer amphora stats show** (octaviaclient/osc/v2/amphora.py:214)

availabilityzone

**loadbalancer availabilityzone create** (octaviaclient/osc/v2/availabilityzone.py:28)

**loadbalancer availabilityzone list** (octaviaclient/osc/v2/availabilityzone.py:105)

**loadbalancer availabilityzone set** (octaviaclient/osc/v2/availabilityzone.py:178)

**loadbalancer availabilityzone unset** (octaviaclient/osc/v2/availabilityzone.py:220)

availabilityzoneprofile

**loadbalancer availabilityzoneprofile list** (octaviaclient/osc/v2/availabilityzoneprofile.py:92)

**loadbalancer availabilityzoneprofile set** (octaviaclient/osc/v2/availabilityzoneprofile.py:152)

flavor

**loadbalancer flavor create** (octaviaclient/osc/v2/flavor.py:30)

**loadbalancer flavor list** (octaviaclient/osc/v2/flavor.py:107)

**loadbalancer flavor set** (octaviaclient/osc/v2/flavor.py:188)

**loadbalancer flavor unset** (octaviaclient/osc/v2/flavor.py:235)

flavorprofile

**loadbalancer flavorprofile list** (octaviaclient/osc/v2/flavorprofile.py:91)

**loadbalancer flavorprofile set** (octaviaclient/osc/v2/flavorprofile.py:158)

healthmonitor

**loadbalancer healthmonitor create** (octaviaclient/osc/v2/health_monitor.py:37)

**loadbalancer healthmonitor delete** (octaviaclient/osc/v2/health_monitor.py:180)

**loadbalancer healthmonitor list** (octaviaclient/osc/v2/health_monitor.py:216)

**loadbalancer healthmonitor set** (octaviaclient/osc/v2/health_monitor.py:279)

**loadbalancer healthmonitor unset** (octaviaclient/osc/v2/health_monitor.py:402)

l7policy

**loadbalancer l7policy create** (octaviaclient/osc/v2/l7policy.py:35)

**loadbalancer l7policy delete** (octaviaclient/osc/v2/l7policy.py:152)

**loadbalancer l7policy list** (octaviaclient/osc/v2/l7policy.py:188)

**loadbalancer l7policy set** (octaviaclient/osc/v2/l7policy.py:258)

**loadbalancer l7policy unset** (octaviaclient/osc/v2/l7policy.py:364)

l7rule

**loadbalancer l7rule create** (octaviaclient/osc/v2/l7rule.py:37)

**loadbalancer l7rule delete** (octaviaclient/osc/v2/l7rule.py:139)

**loadbalancer l7rule list** (octaviaclient/osc/v2/l7rule.py:182)

**loadbalancer l7rule set** (octaviaclient/osc/v2/l7rule.py:254)

**loadbalancer l7rule unset** (octaviaclient/osc/v2/l7rule.py:354)

listener

**loadbalancer listener create** (octaviaclient/osc/v2/listener.py:34)

**loadbalancer listener delete** (octaviaclient/osc/v2/listener.py:274)

**loadbalancer listener list** (octaviaclient/osc/v2/listener.py:309)

**loadbalancer listener set** (octaviaclient/osc/v2/listener.py:404)

**loadbalancer listener unset** (octaviaclient/osc/v2/listener.py:615)

loadbalancer

**loadbalancer create** (octaviaclient/osc/v2/load_balancer.py:34)

**loadbalancer delete** (octaviaclient/osc/v2/load_balancer.py:193)

**loadbalancer failover** (octaviaclient/osc/v2/load_balancer.py:235)

**loadbalancer list** (octaviaclient/osc/v2/load_balancer.py:269)

**loadbalancer set** (octaviaclient/osc/v2/load_balancer.py:420)

**loadbalancer unset** (octaviaclient/osc/v2/load_balancer.py:499)

member

**loadbalancer member create** (octaviaclient/osc/v2/member.py:112)

**loadbalancer member delete** (octaviaclient/osc/v2/member.py:354)

**loadbalancer member list** (octaviaclient/osc/v2/member.py:32)

**loadbalancer member set** (octaviaclient/osc/v2/member.py:249)

**loadbalancer member unset** (octaviaclient/osc/v2/member.py:400)

pool

**loadbalancer pool create** (octaviaclient/osc/v2/pool.py:34)

**loadbalancer pool delete** (octaviaclient/osc/v2/pool.py:195)

**loadbalancer pool list** (octaviaclient/osc/v2/pool.py:227)

**loadbalancer pool set** (octaviaclient/osc/v2/pool.py:298)

**loadbalancer pool unset** (octaviaclient/osc/v2/pool.py:434)

provider

**loadbalancer provider capability list** (octaviaclient/osc/v2/provider.py:44)

quota

**loadbalancer quota list** (octaviaclient/osc/v2/quota.py:29)

**loadbalancer quota set** (octaviaclient/osc/v2/quota.py:98)

**loadbalancer quota unset** (octaviaclient/osc/v2/quota.py:213)

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