magnum — Interactions

Interactions — magnum — branch stable/2026.2

Branch stable/2026.2 @ 1910928b7d9f — repository https://opendev.org/openstack/magnum — analysed on 2026-11-09

Magnum core talks to six kinds of systems: the client (REST), RabbitMQ (RPC between magnum-api and magnum-conductor, plus notifications), MariaDB, Keystone (token validation and the service catalogue), the OpenStack services used to validate requests and store certificates (Glance, Nova, Neutron, Barbican, Cinder, Octavia), and the Kubernetes API of each cluster (health). Everything a driver does (for the Cluster API driver: the Kubernetes API of the management cluster and the OpenStack APIs through CAPO) is described in 08.

flowchart LR
  client[Client / Skyline / openstack CLI] -->|HTTPS REST :9511| api[magnum-api]
  api -->|GET /v3/auth/tokens| ks[Keystone]
  api -->|AMQP cast / call topic magnum-conductor| mq{{RabbitMQ}}
  mq --> cond[magnum-conductor]
  api -->|SQL - uWSGI mode| db[(MariaDB)]
  cond -->|SQL| db
  api -->|REST validation| glance[Glance] & nova[Nova] & neutron[Neutron]
  cond -->|REST secrets + containers| barbican[Barbican]
  cond -->|AMQP notifications magnum.cluster.*| mq
  cond -->|HTTPS mTLS /healthz /api/v1/nodes| k8s[Cluster Kubernetes API]
  cond -->|Python driver API| drv[Driver e.g. magnum-cluster-api]
  drv -->|HTTPS| mgmt[Management cluster API: CAPI objects]

RabbitMQ

Topology

The transport is created from [DEFAULT]/transport_url (magnum/common/rpc.py:56). Clients are cached per (topic, server, timeout) for the life of the process (magnum/common/rpc_service.py:78).

RPC methods

Object versions on the wire (magnum_object.version): Cluster 1.24 (magnum/objects/cluster.py:63), ClusterTemplate 1.21 (magnum/objects/cluster_template.py:47), NodeGroup 1.2 (magnum/objects/nodegroup.py:32), Certificate 1.2, X509KeyPair 1.2, Federation 1.0, Quota 1.0, MagnumService 1.0, Stats 1.0.

Notifications

Only cluster operations are notified; templates, nodegroups, quotas and certificates are not.

publisher_id is container-infra.<[DEFAULT]/host or FQDN> (magnum/common/rpc.py:168). The priority is error when the CADF outcome is failure, info otherwise (magnum/conductor/utils.py:149). The event is built with pycadf (magnum/conductor/utils.py:128): eventType activity, action (create, update, delete), outcome (pending, success, failure), initiator (user, project, domain of the request; empty for the periodic tasks, which run as admin), observer and target of type service/magnum/cluster, and a cluster_data attachment with the cluster fields (magnum/conductor/utils.py:93). One attachment key is misspelt with a trailing colon: docker_volume_size: (magnum/conductor/utils.py:108).

Sample frame (cast cluster_create, AMQP body)

{"oslo.version": "2.0",
 "oslo.message": "{\"method\": \"cluster_create\", \"namespace\": null, \"version\": null,
   \"args\": {\"cluster\": {\"magnum_object.name\": \"Cluster\", \"magnum_object.namespace\": \"magnum\",
       \"magnum_object.version\": \"1.24\",
       \"magnum_object.data\": {\"uuid\": \"5d12f6fd-…\", \"name\": \"k8s-prod\",
         \"cluster_template_id\": \"0b1c…\", \"keypair\": \"ops\", \"labels\": {\"kube_tag\": \"v1.31.4\"},
         \"flavor_id\": \"m1.large\", \"master_flavor_id\": \"m1.medium\", \"project_id\": \"…\", \"user_id\": \"…\",
         \"master_lb_enabled\": true, \"floating_ip_enabled\": true, \"coe_version\": null, \"container_version\": null},
       \"magnum_object.changes\": [\"uuid\", \"name\", \"…\"]},
     \"master_count\": 3, \"node_count\": 4, \"create_timeout\": 60},
   \"_unique_id\": \"…\", \"_context_auth_token\": \"gAAAA…\", \"_context_user_id\": \"…\",
   \"_context_project_id\": \"…\", \"_context_roles\": [\"member\", \"reader\"], \"_context_is_admin\": false,
   \"_context_request_id\": \"req-…\", \"_context_auth_token_info\": {…}}"}

The user's Keystone token and the full token body travel in the context of every message (magnum/common/context.py:66, magnum/common/context.py:79; the context also carries all_tenants, magnum/common/context.py:80): the conductor reuses them to call OpenStack services on the user's behalf. A cast that waits in the queue longer than the token lifetime fails with AuthorizationFailure in the conductor.

Database

oslo.db / SQLAlchemy, [database]/connection. The schema has no foreign keys: integrity is enforced by code (magnum/db/sqlalchemy/models.py). Alembic head: b3e1cf4a2d5e (magnum/db/sqlalchemy/alembic/versions/b3e1cf4a2d5e_add_node_labels_and_node_taints.py).

Tables

Notable transactions

• Template update locks the row (SELECT … FOR UPDATE), then checks whether a cluster uses it before allowing anything other than rename or (un)publish (magnum/db/sqlalchemy/api.py:436): sql SELECT * FROM cluster_template WHERE uuid = :id FOR UPDATE; SELECT 1 FROM cluster WHERE cluster_template_id = :uuid LIMIT 1; UPDATE cluster_template SET … WHERE id = :id;
• Cluster update (save()) also uses SELECT … FOR UPDATE then UPDATE (magnum/db/sqlalchemy/api.py:267), wrapped in retry_on_deadlock. There is no optimistic version column: two conductors saving the same cluster overwrite each other's fields.
• Template visibility is a UNION of the project's templates, the public non-hidden ones and, for admins, the public hidden ones (magnum/db/sqlalchemy/api.py:294).
• Cluster list by size: filtering on node_count sums nodegroup.node_count grouped by cluster_id (magnum/db/sqlalchemy/api.py:139).
• Stats: SELECT COUNT(*) FROM cluster [WHERE project_id = :p] and SELECT SUM(node_count) FROM nodegroup [WHERE project_id = :p] (magnum/db/sqlalchemy/api.py:221).
• Status poller: SELECT * FROM cluster WHERE status IN (…4 states…) every 10 s (magnum/service/periodic.py:166), then one nodegroup list per cluster.

Outbound REST calls

All OpenStack clients are openstacksdk connections built from a keystoneauth session (magnum/common/clients.py). In the API and the conductor the session reuses the user's token (AccessInfoPlugin built from keystone.token_info, magnum/common/keystone.py:66). Without a token, i.e. in the periodic tasks and for the Barbican admin client, it uses the service credentials of [keystone_auth] (magnum/common/keystone.py:73). The endpoint comes from the catalogue, with [<service>]/region_name and endpoint_type (publicURL by default) (magnum/common/clients.py:44).

Because the certificates are created with the service credentials, the Barbican secrets belong to the Magnum service project, not to the user's project. A cluster deleted while Barbican is unreachable leaves its secrets behind, and the etcd and front-proxy CAs are never deleted (magnum/conductor/handlers/common/cert_manager.py:240).

Certificate storage back ends

Certificate formats (magnum/common/x509/operations.py): RSA keys of [x509]/rsa_key_size bits (2048), SHA-256 signatures, CA with BasicConstraints(ca=True, path_length=0) and key usage keyCertSign (magnum/common/x509/operations.py:83), client certificates with clientAuth (magnum/common/x509/operations.py:68), validity [x509]/term_of_validity days (1825).

Other

• Files: when [cluster]/temp_cache_dir (/var/lib/magnum/certificate-cache) exists, the conductor caches each cluster's CA, client key and certificate in clear text under <dir>/<cluster_uuid>/, mode 0600 (magnum/conductor/handlers/common/cert_manager.py:178). The cache is never refreshed after a CA rotation, so the health poller keeps using the old client certificate [inferred: the cache directory is only written when absent, magnum/conductor/handlers/common/cert_manager.py:184]. Otherwise temporary files are created for each poll.
• Drivers: loaded with stevedore from the magnum.drivers entry point (magnum/drivers/common/driver.py:36); [drivers]/disabled_drivers hides some.
• No subprocess, rootwrap, privsep, cache (Memcached/Redis) or coordination back end is used by Magnum core.

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