python-designateclient — Scenarios

Scenarios — python-designateclient — branch stable/2026.2

Branch stable/2026.2 @ 9231eef90192 — repository https://opendev.org/openstack/python-designateclient — analysed on 2026-11-01

The client side of each diagram was [observed] on the local stub. What Designate does after the request was read in reverse-spec-designate, never run. Scenario names refer to _rewrite/defects-repro_stable-2026.2.json.

1. Creating a zone, with discovery

A first command in a process: authentication, discovery, then one POST. The command ends at the 202, while the zone is still PENDING.

sequenceDiagram
  autonumber
  actor U as User
  participant O as openstack
  participant K as Keystone
  participant D as Designate API
  U->>O: zone create example.org. --email a@example.org
  O->>O: check email is set (client side)
  O->>K: POST /v3/auth/tokens
  K-->>O: 201, token with catalog
  O->>D: GET /dns (version document)
  D-->>O: 200 versions, v2 links to /dns/v2
  O->>D: POST /dns/v2/zones {name, type, email}
  alt accepted
    D-->>O: 202 zone, status PENDING
    O-->>U: table of the zone, exit 0
    Note over U,D: the zone becomes ACTIVE later, see zone show
  else duplicate or quota
    D-->>O: 409 or 413 with message
    O-->>U: message on stderr, exit 1
  else 405, 415 or other unlisted 4xx
    D-->>O: fault body
    O-->>U: table of the fault, exit 0
  end

Diagnostics

public endpoint for dns service...: the catalog has no dns entry for that region and interface.
Could not find requested endpoint: the version document offers no v2.
A 404 on /dns/zones or similar: the root gave no version document and the catalog URL has no /v2. --debug shows the URL.
A table with code and type rows: an unlisted 4xx (defect 3).

2. Creating a recordset with a relative name, on a zone given by name

The most chatty command: three requests.

sequenceDiagram
  autonumber
  actor U as User
  participant O as openstack
  participant D as Designate API
  U->>O: recordset create example.org. www --type A --record 192.0.2.1
  O->>D: GET /zones?name=example.org.
  alt one match
    D-->>O: 200 {zones: [zone]}
  else no match
    D-->>O: 200 {zones: []}
    O-->>U: Name example.org. didn't resolve, exit 1
  else several
    D-->>O: 200 {zones: [a, b]}
    O-->>U: Multiple matches found for {name}..., exit 1
  end
  O->>D: GET /zones/{id}
  D-->>O: 200 zone
  O->>D: POST /zones/{id}/recordsets {name: www.example.org., type, records}
  D-->>O: 201 or 202 recordset
  O-->>U: table, records joined by newlines

Scenario recordset-create-zone-name. With a zone UUID and a name ending in ., only the POST remains (recordset-create-fqdn).

Diagnostics: 'records' on stderr means the response had no records key, although the recordset may exist. The literal {name} in the message is defect 4.

3. Deleting a zone, with its flags

sequenceDiagram
  autonumber
  actor U as User
  participant O as openstack
  participant D as Designate API
  U->>O: zone delete example.org. --hard-delete --delete-shares
  O->>D: GET /zones?name=example.org.
  D-->>O: 200 {zones: [zone]}
  O->>D: DELETE /zones/{id}, X-Designate-Hard-Delete True, X-Designate-Delete-Shares true
  alt body returned
    D-->>O: 202 zone, action DELETE
    O-->>U: table, exit 0
  else no body
    D-->>O: 202 empty
    O-->>U: 'str' object has no attribute 'pop', exit 1
    Note over U,D: the delete was accepted anyway
  end

Scenarios hdr-hard-delete-shares, zone-delete-empty-202.

Diagnostics: in the interactive shell, --hard-delete stays on the client for commands that lack that option, until another zone delete resets it (defect 8). Check with --debug before any destructive command in such a session.

4. Transferring a zone between two projects

Two users, two processes.

sequenceDiagram
  autonumber
  actor A as Owner
  actor B as Recipient
  participant D as Designate API
  A->>D: POST /zones/{id}/tasks/transfer_requests {target_project_id, description}
  D-->>A: 201 {id, key, status ACTIVE}
  A-->>B: id and key, out of band
  B->>D: POST /zones/tasks/transfer_accepts {key, zone_transfer_request_id}
  alt key valid
    D-->>B: 201 {id, status, zone_id}
    B->>D: GET /zones/tasks/transfer_accepts/{id}
    D-->>B: 200 status COMPLETE
  else invalid
    D-->>B: 4xx with message
  end

Commands: zone transfer request create, zone transfer accept request, zone transfer accept show. The client does not wait for COMPLETE. The key is displayed by zone transfer request list and show, so it should be treated as a secret. Without --target-project-id, the body holds target_project_id: null.

Diagnostics: status and bodies of the accept are in reverse-spec-designate; on the client side, exit 0 only means that the accept was recorded.

5. Export then import

sequenceDiagram
  autonumber
  actor U as User
  participant O as openstack
  participant F as Local file
  participant D as Designate API
  U->>O: zone export create example.org.
  O->>D: GET /zones?name=example.org.
  D-->>O: 200 {zones: [zone]}
  O->>D: POST /zones/{id}/tasks/export
  D-->>O: 202 {id, status PENDING}
  loop the user polls by hand
    U->>O: zone export show ID
    O->>D: GET /zones/tasks/exports/{id}
    D-->>O: 200 {status}
  end
  U->>O: zone export showfile ID
  O->>D: GET /zones/tasks/exports/{id}/export, Accept text/dns
  D-->>O: 200 text
  O-->>U: table with one data row
  U->>F: save the text
  U->>O: zone import create file
  O->>F: open and read
  O->>D: POST /zones/tasks/imports, Content-Type text/dns
  D-->>O: 202 {id, status PENDING}

Scenarios hdr-export-accept, import-plain, import-attributes.

Diagnostics: zone export showfile prints inside a table by default, so the output is not a usable zone file as it stands; -f value is the way out [inferred, from cliff formatters, not run]. A 406 on this route prints the fault as data and exits 0 (defect 3).

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