zun — Interactions

Interactions — zun — branch stable/2026.2

Branch stable/2026.2 @ 34135a563699 — repository https://opendev.org/openstack/zun — analysed on 2026-11-01

All frames below are reconstructed from the code. No capture of a real system was made, since none was available.

RabbitMQ

Library: oslo.messaging (zun/common/rpc_service.py:17). Transport: [DEFAULT]/transport_url. Control exchange: zun (zun/common/config.py:33). allowed_remote_exmods carries zun.common.exception (zun/common/rpc.py:36), so a remote exception keeps its class and status when it reaches the API.

Topology

Only zun-api sends RPC. zun-compute does not call other services over the bus. There is no conductor: every process with a role writes the database directly.

RPC methods

Client: zun/compute/rpcapi.py. Server: zun/compute/manager.py. Topic and server resolved at zun/common/rpc_service.py:98, zun/common/rpc_service.py:102. The target carries no version (zun/common/rpc_service.py:51). Client history states 1.0 and 1.1 in a comment, but the value is not sent (zun/compute/rpcapi.py:44).

container_rebuild, start, stop and other casts do not check the node, so a request to a dead node gives 202 and is lost until the queue is consumed. "Host check" is check_container_host (zun/compute/rpcapi.py:25). container is a versioned object: Container 1.44, Capsule 1.4, CapsuleContainer 1.4, CapsuleInitContainer 1.4 (zun/objects/container.py:431, zun/objects/container.py:443, zun/objects/container.py:487, zun/objects/container.py:517).

Notifications

None. A search over the non-test code finds no get_notifier and no caller passing notifier= to wrap_exception (zun/common/exception.py:56).

Sample frame

Cast container_start to zun-compute.node1:

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"container_start\", \"args\": {\"container\": {\"zun_object.name\": \"Container\", \"zun_object.namespace\": \"zun\", \"zun_object.version\": \"1.44\", \"zun_object.data\": {\"uuid\": \"…\", \"status\": \"Created\", \"host\": \"node1\", \"container_id\": \"…\"}}}, \"namespace\": null, \"_unique_id\": \"…\", \"_context_project_id\": \"…\", \"_context_user_id\": \"…\", \"_context_auth_token\": \"…\", \"_context_request_id\": \"req-…\", \"_context_roles\": [\"member\"]}"}

The zun_object prefix is OBJ_SERIAL_NAMESPACE (zun/objects/base.py:38). The context travels in _context_*, including the user's token, which zun-compute reuses to call Neutron, Cinder and Glance (zun/common/keystone.py:72). A long image pull can outlive that token [inferred]; capsule and auto-remove flows that run later rely on it too.

Database

Library: oslo.db and SQLAlchemy (zun/db/sqlalchemy/api.py:19). Single backend sqlalchemy (zun/db/api.py:27); zun/db/etcd/__init__.py is an empty leftover. Access from zun-api, zun-compute, zun-cni-daemon, zun-wsproxy. Migrations: Alembic, head 3f2b36231bee, 84 revisions, run with zun-db-manage upgrade (zun/cmd/db_manage.py:28). They do not run on SQLite. Schema: [_rewrite/schema-mariadb-migrated_stable-2026.2.sql](_rewrite/schema-mariadb-migrated_stable-2026.2.sql), differences with the models in [_rewrite/schema-diff_stable-2026.2.md](_rewrite/schema-diff_stable-2026.2.md).

Tables

Notable transactions

• Updates: a SELECT … FOR UPDATE then assignment, in the same transaction, with retry_on_deadlock (zun/db/sqlalchemy/api.py:251, zun/db/sqlalchemy/api.py:258). 12 sites. No optimistic generation, no status compare-and-swap: the last writer wins, and task_state is an advisory marker.
• Container update rejects a name change that breaks uniqueness: SELECT … WHERE name = ? [AND project_id = ?] according to unique_container_name_scope (zun/db/sqlalchemy/api.py:165, zun/db/sqlalchemy/api.py:240). A check then write, so not race-free.
• Project scope: filter added by _add_project_filters unless admin with all_projects (zun/db/sqlalchemy/api.py:111).
• Quotas: read-then-check, not reservations: SELECT SUM(...), then compare; two concurrent requests can both pass (zun/api/controllers/v1/containers.py:463, zun/common/quota.py:166, zun/common/quota.py:568).
• Registry password: Fernet with auth_encryption_key, decrypted on read and copied in clear in the RPC object (zun/db/sqlalchemy/api.py:1402, zun/db/sqlalchemy/api.py:1414, zun/common/crypt.py:23, zun/conf/utils.py:21).
• Foreign keys: container.capsule_id cascades; volume_mapping.volume_id cascades; container_actions.container_uuid cascades; see _rewrite/schema-mariadb-migrated_stable-2026.2.sql.

Cache

oslo.cache is not used in the code read. keystonemiddleware's own token cache may be configured with [keystone_authtoken]/memcached_servers.

Outbound REST calls

Identity: [keystone_auth] for admin clients, and [keystone_authtoken]/www_authenticate_uri for token auth (zun/conf/keystone.py:16, zun/conf/keystone.py:17). Selection: auth_token_info, else the user's token, else admin credentials (zun/common/keystone.py:72).

Port creation is the sensitive one: tenant_id is the caller's project and the call is admin, while the requested network was first read with the user's token (zun/common/utils.py:508).

Docker daemon

• Protocol: Docker Engine API, version [docker]/docker_remote_api_version, 1.40 by default (zun/conf/docker.py:20). Library: docker-py (zun/container/docker/utils.py:52).
• Endpoints: unix:///var/run/docker.sock for zun-compute, and tcp://$my_ip:2375 for zun-wsproxy (zun/conf/docker.py:28, zun/conf/docker.py:31, zun/conf/docker.py:49). The install guide opens 2375 on the node with no TLS setting (doc/source/install/compute-install.rst:224). TLS exists through api_insecure, ca_file, cert_file, key_file (zun/container/docker/utils.py:35).
• Errors: is_not_found is '404' in str(e), so an error whose text merely contains 404 counts as not found (zun/container/docker/driver.py:47). errors.APIError is rewritten to DockerError (zun/container/docker/utils.py:48); wrap_docker_error turns "not found" into state changes and "not running", "not paused", "paused" into Conflict (zun/container/docker/driver.py:62, zun/container/docker/driver.py:87).
• Time-out: [docker]/default_timeout, 60 s.
• Names: zun-<uuid>.
• Calls: create_container, start, stop, restart, kill, pause, unpause, remove_container, inspect_container, list_containers, logs, exec_create, exec_start, exec_inspect, exec_resize, resize, top, stats, update_container, get_archive, put_archive, commit, pull, load_image, inspect_image, get_image, images, info, create_network, remove_network, networks, connect_container_to_network, disconnect_container_from_network.

Isolation applied through Docker and CRI

Other

• Images: selection image_driver per container, default_image_driver default docker, list image_driver_list glance, docker (zun/conf/image_driver.py:20, zun/conf/image_driver.py:32). Pull policy always when unset (zun/common/utils.py:252). With Docker, policies ifnotpresent and never look at the node's store, with no project check (zun/image/docker/driver.py:54, zun/image/docker/driver.py:90). With Glance: image located with the user's token, container_format: docker, tar written to [glance]/images_directory, docker load (zun/image/glance/utils.py:56, zun/image/glance/driver.py:74, zun/container/docker/driver.py:128).
• Capsule images under CRI: PullImage only; the registry is not usable (zun/container/cri/driver.py:194).
• containerd CRI: gRPC over unix:///run/containerd/containerd.sock, runtime.v1alpha2, insecure channel (zun/container/cri/driver.py:45, zun/criapi/api_pb2.py:31).
• CNI: zun-cni binary called with CNI_* environment and config on stdin (zun/network/cni_network.py:132); talks HTTP to zun-cni-daemon at 127.0.0.1:9036 (zun/conf/cni_daemon.py:24). Spec version 0.3.1 (zun/cni/api.py:35). Bindings through os-vif: VIFBridge, VIFOpenVSwitch (setup.cfg:82).
• Kuryr: kuryr-libnetwork is a Docker network plugin, called by Docker rather than by Zun. Zun names the driver with [network]/driver_name (zun/conf/network.py:23).
• Privileged commands: mount, umount, mkfs through rootwrap or privsep (zun/common/mount.py:44, zun/common/utils.py:343). Filter file: etc/zun/rootwrap.d/zun.filters:1. os-brick connects the Cinder device (zun/volume/cinder_workflow.py:62).
• Files: volumes under [volume]/volume_dir, $state_path/mnt/<volume uuid> (zun/common/mount.py:168, zun/conf/volume.py:35); Docker root measured through psutil (zun/container/docker/driver.py:1091).
• Host capabilities: NUMA, memory and PCI information read locally (zun/container/os_capability/linux/os_capability_linux.py:1).
• WebSocket: see 05 § zun-wsproxy.

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