magnum — Driver magnum cluster api

Cluster API driver (magnum-cluster-api) — magnum — branch stable/2026.2

Driver repository https://github.com/vexxhost/magnum-cluster-api @ v0.39.0 (066fdc2) — analysed on 2026-11-09 — paired with Magnum stable/2026.2 @ 1910928

Reference convention: magnum-cluster-api:<path>:<line> points into the driver clone at tag v0.39.0 (full SHA 066fdc23d45f2d0f9a0633bc7c9b61e2f64e4268); magnum:<path>:<line> points into the Magnum clone at 1910928. Statements marked [inferred] were not traced to the end.

Tag choice: v0.39.0 is the latest tag and the first release whose changelog says it runs under Magnum 2026.2 ("run under Magnum 2026.2, which dropped eventlet and novaclient", magnum-cluster-api:CHANGELOG.md:17). The driver supports both eventlet (≤ 2026.1) and native threads (2026.2) by detecting the eventlet patcher (magnum-cluster-api:magnum_cluster_api/utils.py:63-91).

1. Overview

magnum-cluster-api is an out-of-tree Magnum driver that turns a Magnum cluster into a **Cluster API (CAPI) topology-managed Cluster** reconciled by the CAPI core, kubeadm bootstrap / control-plane providers and CAPO (Cluster API Provider OpenStack). The driver itself never creates Nova servers: it writes Kubernetes objects into a management cluster (namespace magnum-system) and reads their status back.

Code layout:

Key design facts:

• One shared ClusterClass per driver release, named magnum-<git describe> (e.g. magnum-v0.39.0) (magnum-cluster-api:src/lib.rs:17-18), re-applied on every create/upgrade (magnum-cluster-api:src/driver.rs:302-319). All per-cluster differences are topology variables consumed by ClusterClass JSON patches (magnum-cluster-api:src/resources.rs:144-153).
• CAPI name ≠ Magnum UUID: the CAPI Cluster is named kube-<5 random [a-z0-9]> and stored in Magnum's cluster.stack_id (magnum-cluster-api:magnum_cluster_api/utils.py:113-123, magnum-cluster-api:magnum_cluster_api/driver.py:81-82).
• Status is polled, not watched: Magnum's periodic sync_cluster_status calls update_cluster_status (magnum:magnum/service/periodic.py:66-71, magnum:magnum/service/periodic.py:161-169).
• No Heat, needs_trust = False (magnum-cluster-api:magnum_cluster_api/driver.py:47); CAPO/CCM/CSI authenticate with a per-cluster Keystone application credential (magnum-cluster-api:magnum_cluster_api/driver.py:98-102).
• A distributed lock (sherlock KubernetesLock, name cluster-<uuid>, namespace magnum-system, expiry 60 s) serialises every mutating call and the status sync across conductors (magnum-cluster-api:magnum_cluster_api/sync.py:18-36, magnum-cluster-api:magnum_cluster_api/driver.py:37-43).

2. Driver interface implemented

Registration: five magnum.drivers entry points (magnum-cluster-api:pyproject.toml:68-73), one per OS; all share BaseDriver and differ only in provides (server_type is always vm, coe always kubernetes). Config options are exported with oslo.config.opts (magnum-cluster-api:pyproject.toml:75).

The Magnum cluster template's cluster_distro (image os_distro) selects the driver; get_operating_system then maps it by prefix to ubuntu|debian|flatcar|rockylinux for the operatingSystem variable (magnum-cluster-api:magnum_cluster_api/utils.py:46, magnum-cluster-api:magnum_cluster_api/utils.py:545-550).

Methods (base contract in magnum:magnum/drivers/common/driver.py:199-308):

3. Objects created on the management cluster

3.1 Management cluster access

• Python side: pykube.HTTPClient(pykube.KubeConfig.from_env()) — KUBECONFIG env or in-cluster service account (magnum-cluster-api:magnum_cluster_api/clients.py:173-174).
• Rust side: one process-wide kube::Client::try_default() (same resolution rules), cached in a OnceCell to avoid FD leaks (magnum-cluster-api:src/clients/kubernetes.rs:37-60).
• Workload cluster access: kubeconfig read from the CAPI-generated secret <stack_id>-kubeconfig, key value, in magnum-system (magnum-cluster-api:src/magnum.rs:247-287). Used only during upgrade to delete legacy addon workloads (magnum-cluster-api:src/driver.rs:82-105) and by the autoscaler (clusterAPIKubeconfigSecret) (magnum-cluster-api:magnum_cluster_api/resources.py:82).
• There is no driver option for the management kubeconfig: everything is in the hard-coded namespace magnum-system (magnum-cluster-api:magnum_cluster_api/driver.py:51).
• Write semantics: Rust create_or_update = GET → replace with resourceVersion, retried with exponential backoff on HTTP 409; 404 → create (magnum-cluster-api:src/clients/kubernetes.rs:153-176). Topology edits from Python use server-side apply with fieldManager=atmosphere-operator, force=true (magnum-cluster-api:magnum_cluster_api/utils.py:589-607). Upgrade uses a GET/replace of metadata.labels, spec.clusterNetwork, spec.topology with 409 retry (magnum-cluster-api:src/client.rs:73-107).

3.2 Object catalogue

Objects created by CAPI/CAPO from the topology (not by the driver) but read by the driver: KubeadmControlPlane, MachineDeployment (label topology.cluster.x-k8s.io/deployment-name=<ng.name>), Machine, OpenStackMachine, OpenStackCluster, <stack_id>-kubeconfig secret (magnum-cluster-api:magnum_cluster_api/objects.py:72-98, magnum-cluster-api:magnum_cluster_api/driver.py:562-569).

Addons delivered to the workload cluster (via CRS, namespace kube-system):

Image mirroring: when container_infra_prefix is set, every image is rewritten to the private registry with fixed rules (calico, cilium, k8scloudprovider, sig-storage, provider-os, coredns, autoscaling, etcd/kube-*/pause) (magnum-cluster-api:magnum_cluster_api/image_utils.py:42-77).

flowchart LR
  subgraph Magnum
    MC[Magnum cluster uuid + stack_id]
  end
  subgraph mgmt["Management cluster, ns magnum-system"]
    CC[ClusterClass magnum-vX.Y.Z]
    OCT[OpenStackClusterTemplate]
    OMT[OpenStackMachineTemplate]
    KCPT[KubeadmControlPlaneTemplate]
    KCT[KubeadmConfigTemplate]
    CL[Cluster stack_id\nlabel cluster-uuid]
    CCS[Secret stack_id-cloud-config\nclouds.yaml app cred]
    CAS[Secrets stack_id-ca/-etcd/-proxy/-sa]
    LS[Secret uuid legacy addons]
    CPS[Secret stack_id-cloud-provider]
    CRS1[CRS uuid]
    CRS2[CRS stack_id-cloud-provider Reconcile]
    AS[Helm release stack_id autoscaler]
    KCP[KubeadmControlPlane]
    MD[MachineDeployment per nodegroup]
    M[Machine / OpenStackMachine]
    OSC[OpenStackCluster]
    KC[Secret stack_id-kubeconfig]
  end
  subgraph OpenStack
    NOVA[Nova servers + server groups]
    NEU[Neutron net/subnet/router/SG/FIP]
    OCTA[Octavia API LB]
    CIN[Cinder boot/etcd/docker volumes]
  end
  subgraph Workload["Workload cluster kube-system"]
    CNI[Cilium or Calico]
    CCM[OpenStack CCM]
    CSI[Cinder / Manila CSI]
    KA[k8s-keystone-auth]
  end
  MC --> CL
  CC --> OCT & OMT & KCPT & KCT
  CL -- topology.class --> CC
  CL --> KCP & MD & OSC
  KCP --> M
  MD --> M
  CCS -. identityRef .-> OSC & M
  CAS -. kubeadm CA .-> KCP
  OSC --> NEU & OCTA
  M --> NOVA & CIN
  CL --> KC
  LS --> CRS1 --> CNI & KA
  CPS --> CRS2 --> CCM & CSI
  KC -.-> AS

4. Field / label mapping (Magnum → CAPI / CAPO)

Unless stated, the target is a **CAPI Cluster.spec.topology.variables[] entry**, then a ClusterClass JSON patch writes it into the concrete template. Label values are strings; booleans are parsed with strutils.bool_from_string(strict=True) and integers with validate_integer (magnum-cluster-api:magnum_cluster_api/utils.py:327-356). Cluster labels are Magnum's merged template+cluster labels; nodegroup labels are used for per-MD overrides.

4.1 Cluster / template fields

4.2 Cluster labels

Variables are first passed through resolve_immutable_fields: for each mapped path, the value **already present on the live OpenStackCluster wins over the label**, so LB provider/flavor/AZ and disableAPIServerFloatingIP never change after creation (CAPO's webhook rejects changes) (magnum-cluster-api:src/immutable_fields.rs:66-100, magnum-cluster-api:src/immutable_fields.rs:159-196, magnum-cluster-api:magnum_cluster_api/resources.py:951-953).

4.3 Nodegroup → topology.workers.machineDeployments[]

On existing MDs only replicas/annotations/labels/nodeVolumeDetachTimeout (and an empty→set failureDomain) are changed; variables are frozen to avoid rolling updates (magnum-cluster-api:magnum_cluster_api/resources.py:776-789). Nodegroups with role master or status DELETE* are excluded (magnum-cluster-api:magnum_cluster_api/resources.py:857-868). The master nodegroup is represented only by topology.controlPlane; its image_id is the cluster imageUUID (magnum-cluster-api:magnum_cluster_api/resources.py:946).

5. Status reconciliation

Triggers (Magnum core): sync_cluster_status periodic task selects clusters in CREATE/UPDATE/DELETE/ROLLBACK_IN_PROGRESS and calls driver.update_cluster_status; on DELETE_COMPLETE Magnum destroys certificates, nodegroups and the cluster row (magnum:magnum/service/periodic.py:66-91, magnum:magnum/service/periodic.py:161-169). sync_cluster_health_status calls get_monitor().poll_health_status() and stores health_status/health_status_reason (magnum:magnum/service/periodic.py:104-125, magnum:magnum/conductor/monitors.py:58-66).

5.1 Control-plane nodegroup (KubeadmControlPlane)

update_cluster_control_plane_status (magnum-cluster-api:magnum_cluster_api/driver.py:166-198):

1. action = prefix of the current master nodegroup status (CREATE, UPDATE, …); if KCP status.observedGeneration > 1 the action becomes UPDATE (lines 172-180).
2. updatedReplicas != replicas → <action>_IN_PROGRESS (lines 188-189).
3. updatedReplicas == replicas == ng.node_count and status.ready → <action>_COMPLETE (lines 190-193).
4. status_reason = KCP status.failureMessage (line 194). No _FAILED is ever derived.

5.2 Worker nodegroups (MachineDeployment)

update_nodegroups_status (magnum-cluster-api:magnum_cluster_api/driver.py:501-610):

5.3 Cluster

update_cluster_status (magnum-cluster-api:magnum_cluster_api/driver.py:200-313), under the cluster lock, after cluster.refresh():

• CREATE_IN_PROGRESS / UPDATE_IN_PROGRESS: if no CAPI Cluster yet → return. Builds a map of CAPI Cluster.status.conditions; if any of ControlPlaneReady, InfrastructureReady, Ready is not "True" (missing counts as not true) → status_reason = "CAPI Cluster status: <reason>: <message>. CAPI OpenstackCluster status reason: <reason>: <message>" from the latest Kubernetes Event of the Cluster and of the OpenStackCluster, save, return (lines 222-244, 140-164). Otherwise:
  • api_address = "https://<controlPlaneEndpoint.host>:<port>", coe_version = spec.topology.version (lines 246-250);
  • on create with autoscaling, helm upgrade --install the autoscaler (lines 254-258);
  • if any nodegroup (incl. master) is not *_COMPLETE → return (lines 260-270);
  • CREATE_IN_PROGRESS → CREATE_COMPLETE, UPDATE_IN_PROGRESS → UPDATE_COMPLETE, status_reason = None (lines 272-279).
• DELETE_IN_PROGRESS: while the CAPI Cluster exists → refresh status_reason from events, return. When gone → delete application credential <uuid> (Forbidden/NotFound ignored), cloud-config secret, 4 CA secrets, all Nova server groups → DELETE_COMPLETE (lines 281-313, magnum-cluster-api:magnum_cluster_api/clients.py:52-73).
• **No *_FAILED state is produced by the driver.** _FAILED comes only from Magnum core when a driver call raises (magnum:magnum/conductor/handlers/cluster_conductor.py:77-79, magnum:magnum/conductor/handlers/cluster_conductor.py:181-185, magnum:magnum/conductor/handlers/nodegroup_conductor.py:85-89). A CAPI cluster that never becomes Ready stays *_IN_PROGRESS forever (cluster_create_timeout is ignored).
• Not filled: node_addresses, master_addresses, discovery_url (no reference in the driver; [inferred] by grep absence).

5.4 Health monitor

Rust Monitor.poll_health_status (magnum-cluster-api:src/monitor.rs:131-185): lists Machines and KubeadmControlPlane labelled cluster.x-k8s.io/cluster-name=<stack_id>; HEALTHY iff KCP condition Available=True and every Machine NodeHealthy=True; health_status_reason = {"<infraRef name>.Ready": "True|False", "api": "ok|nok"}; UNKNOWN if no stack_id (magnum-cluster-api:src/monitor.rs:18-49, magnum-cluster-api:src/monitor.rs:75-89). With autoscaling, the Python monitor also copies each MD's spec.replicas into nodegroup.node_count (magnum-cluster-api:magnum_cluster_api/monitor.py:31-51).

stateDiagram-v2
  [*] --> CREATE_IN_PROGRESS: conductor create_cluster OK
  [*] --> CREATE_FAILED: driver raised (Magnum core)
  CREATE_IN_PROGRESS --> CREATE_IN_PROGRESS: CAPI Cluster absent or ControlPlaneReady/InfrastructureReady/Ready != True (status_reason = last events)
  CREATE_IN_PROGRESS --> CREATE_IN_PROGRESS: conditions True but a nodegroup not *_COMPLETE
  CREATE_IN_PROGRESS --> CREATE_COMPLETE: conditions True and all nodegroups *_COMPLETE (api_address, coe_version set)
  CREATE_COMPLETE --> UPDATE_IN_PROGRESS: resize / nodegroup create-update-delete / upgrade
  UPDATE_COMPLETE --> UPDATE_IN_PROGRESS: idem
  UPDATE_IN_PROGRESS --> UPDATE_COMPLETE: conditions True and all nodegroups *_COMPLETE
  UPDATE_IN_PROGRESS --> UPDATE_FAILED: driver raised (Magnum core)
  CREATE_COMPLETE --> DELETE_IN_PROGRESS: delete_cluster OK
  UPDATE_COMPLETE --> DELETE_IN_PROGRESS: delete_cluster OK
  DELETE_IN_PROGRESS --> DELETE_IN_PROGRESS: CAPI Cluster still exists
  DELETE_IN_PROGRESS --> DELETE_COMPLETE: CAPI Cluster gone, app cred + secrets + server groups removed
  [*] --> DELETE_FAILED: delete_cluster raised (Magnum core)
  DELETE_COMPLETE --> [*]: Magnum destroys rows

6. Credentials and certificates

• Application credential per cluster, created in the context of the requesting user: name = cluster UUID, description Magnum cluster (<uuid>), user = cluster.user_id, unrestricted roles [inferred: no roles/access_rules passed] (magnum-cluster-api:magnum_cluster_api/driver.py:98-102, magnum-cluster-api:magnum_cluster_api/clients.py:37-50). Deleted only once the CAPI Cluster is gone, so CAPO keeps access during teardown (magnum-cluster-api:magnum_cluster_api/driver.py:287-294).
• CAPO identity: secret <stack_id>-cloud-config with clouds.yaml (cloud default, region_name = Cinder region, endpoint_type from [capi_client] endpoint_type minus URL, verify = not [capi_client] insecure, auth_url from the catalog) and cacert = [capi_client] ca_file content or the certifi bundle (magnum-cluster-api:magnum_cluster_api/resources.py:635-699). Referenced by identityRef.name of OpenStackCluster and OpenStackMachines (magnum-cluster-api:src/features/cluster_identity.rs:53-74).
• CCM / Cinder CSI: workload secret kube-system/cloud-config with cloud.conf built by re-reading the app credential from <stack_id>-cloud-config: [Global] auth-url (public identity endpoint), region, application-credential-id/secret, tls-insecure from Magnum [drivers] verify_ca, ca-file=/etc/config/ca.crt when Magnum has an OpenStack CA; [LoadBalancer] lb-provider, lb-method, create-monitor (magnum-cluster-api:magnum_cluster_api/utils.py:144-188, magnum-cluster-api:magnum_cluster_api/resources.py:243-260). The CSI chart mounts that secret (secret.name: cloud-config) (magnum-cluster-api:src/addons/cinder_csi.rs:182-187).
• Manila CSI: workload secret kube-system/csi-manila-secrets with os-authURL, os-region, os-applicationCredentialID/Secret, os-TLSInsecure, optional os-certAuthorityPath (magnum-cluster-api:magnum_cluster_api/utils.py:191-225).
• Keystone webhook: k8s-keystone-auth gets auth_url (public, /v3 appended), Magnum's OpenStack CA and a policy from [kubernetes] keystone_auth_default_policy (file, $PROJECT_ID substituted) or a built-in policy (role member in the cluster's project may list pods/services/deployments/pvc in default) (magnum-cluster-api:magnum_cluster_api/resources.py:465-495, magnum-cluster-api:magnum_cluster_api/utils.py:566-586). The apiserver calls it at https://127.0.0.1:8443/webhook with insecure-skip-tls-verify: true (magnum-cluster-api:data/keystone-auth/webhook.yaml:7-8).
• Certificates — Magnum CA is the kubeadm CA: Magnum core generates the cluster CAs before calling the driver (magnum:magnum/conductor/handlers/cluster_conductor.py:62-63); the driver uploads them as CAPI-format secrets <stack_id>-ca (Kubernetes CA, ca_cert_ref), -etcd (etcd_ca_cert_ref), -proxy (front_proxy_ca_cert_ref), -sa (service-account key pair from magnum_cert_ref) with decrypted private keys (magnum-cluster-api:magnum_cluster_api/resources.py:558-632). kubeadm then signs component certs from these CAs, so magnum ca-show / ca-sign stay consistent. KCP renews leaf certs 21 days before expiry (magnum-cluster-api:src/features/mod.rs:194-196). CA rotation is not supported (magnum-cluster-api:magnum_cluster_api/driver.py:726-728).
• Kubelet serving certificates (optional): serverTLSBootstrap + external cluster-api-csr-approver in the management cluster (magnum-cluster-api:docs/admin/kubelet-serving-certificates.md:14-15).

7. Operations

7.1 Create

sequenceDiagram
  participant MC as Magnum conductor
  participant D as Driver (Py + Rust)
  participant K as Mgmt K8s API (magnum-system)
  participant C as CAPI / KCP / CAPO controllers
  participant OS as Nova / Neutron / Octavia / Cinder / Keystone
  MC->>MC: generate cluster CAs (cert_manager)
  MC->>D: create_cluster(ctx, cluster, timeout)
  D->>K: GET Cluster kube-xxxxx (name uniqueness, retry on conflict)
  D->>MC: cluster.stack_id = kube-xxxxx; save
  D->>K: apply Namespace, 4 templates, ClusterClass magnum-vX
  D->>K: apply CRS <uuid>, CRS <stack_id>-cloud-provider
  D->>OS: validate network driver / master_count / fixed net+subnet (Neutron)
  D->>K: acquire lock cluster-<uuid>
  D->>OS: Keystone create application credential <uuid>
  D->>K: Secret <stack_id>-cloud-config, Secrets -ca -etcd -proxy -sa
  D->>OS: Nova ensure server groups <stack_id>, <stack_id>-<ng>
  D->>OS: Cinder volume types, Glance image, Nova flavors, Keystone catalog
  D->>K: Secret <uuid> (CNI, keystone-auth), Secret <stack_id>-cloud-provider (CCM, CSI, StorageClasses)
  D->>K: create Cluster <stack_id> (topology + variables)
  D-->>MC: return (status CREATE_IN_PROGRESS)
  C->>K: watch Cluster, render OpenStackCluster/KCP/MD from ClusterClass patches
  C->>OS: Neutron network/subnet/router/SGs, Octavia API LB (+FIP)
  C->>OS: Nova servers (+Cinder boot/etcd/docker volumes, server group hints)
  C->>K: Secret <stack_id>-kubeconfig, conditions Ready
  C->>K: CRS applies CNI/CCM/CSI/keystone-auth into the workload cluster
  loop periodic sync_cluster_status
    MC->>D: update_cluster_status
    D->>K: read KCP, MDs, OpenStackMachines, Cluster conditions, Events
    D->>K: helm upgrade --install autoscaler (if enabled, once API up)
    D-->>MC: CREATE_COMPLETE, api_address, coe_version
  end

Sources: magnum-cluster-api:magnum_cluster_api/driver.py:70-138, magnum-cluster-api:src/driver.rs:302-310, magnum-cluster-api:magnum_cluster_api/resources.py:1297-1313.

Note the order: the Rust create_cluster (ClusterClass and CRSs) runs before validate_cluster, so a rejected cluster still leaves two CRS objects (deleted later by delete_cluster) (magnum-cluster-api:magnum_cluster_api/driver.py:84-86).

7.2 Resize / nodegroup operations

sequenceDiagram
  participant MC as Magnum conductor
  participant D as Driver
  participant K as Mgmt K8s API
  participant C as CAPI / CAPO
  participant OS as Nova / Cinder
  MC->>D: resize_cluster(node_count, nodes_to_remove, ng)
  D->>K: lock cluster-<uuid>; strip empty failureDomain (JSON patch)
  opt nodes_to_remove
    D->>K: list Machines (cluster-name, deployment-name)
    D->>K: annotate matching Machine cluster.x-k8s.io/delete-machine=yes
  end
  alt ng.role == master
    D->>K: SSA Cluster topology.controlPlane.replicas = node_count
  else worker
    D->>OS: ensure Nova server group <stack_id>-<ng>
    D->>K: SSA Cluster machineDeployments[ng].replicas (or autoscaler annotations)
  end
  D->>MC: ng + cluster UPDATE_IN_PROGRESS
  C->>K: MachineSet scale (annotated machines deleted first)
  C->>OS: create / delete Nova servers and volumes
  MC->>D: update_cluster_status (periodic) -> UPDATE_COMPLETE

Create nodegroup appends a new MD entry (magnum-cluster-api:magnum_cluster_api/driver.py:473-499); delete nodegroup removes it, and the periodic sync later deletes the server group and marks DELETE_COMPLETE (magnum-cluster-api:magnum_cluster_api/driver.py:682-720, magnum-cluster-api:magnum_cluster_api/driver.py:535-544). No-op detection: identical replicas / MD spec → return without status change (magnum-cluster-api:magnum_cluster_api/driver.py:646-668).

Autoscaler: cluster-autoscaler runs in the management cluster (one Helm release per cluster, image [auto_scaling] image_repository/cluster-autoscaler:v<per-minor>) and scales MDs through the CAPI provider; replicas are left unset in the topology (magnum-cluster-api:magnum_cluster_api/images.py:23-49, magnum-cluster-api:magnum_cluster_api/resources.py:750-753).

Auto-healing: CAPI MachineHealthCheck generated by the ClusterClass (Ready False/Unknown for 5 min, maxUnhealthy 80 %), enabled per topology flag auto_healing_enabled (magnum-cluster-api:src/resources.rs:46-61, magnum-cluster-api:src/resources.rs:96-111).

7.3 Upgrade

sequenceDiagram
  participant MC as Magnum conductor
  participant D as Driver
  participant K as Mgmt K8s API
  participant W as Workload K8s API
  participant C as CAPI / KCP / CAPO
  participant OS as Nova / Glance
  MC->>D: upgrade_cluster(cluster, new_template, ...)
  D->>D: cluster.template_id, labels.kube_tag; every ng: image_id, kube_tag, UPDATE_IN_PROGRESS
  D->>K: strip empty failureDomain
  D->>K: apply ClusterClass magnum-<new driver version>
  D->>W: delete legacy CCM/CSI workloads (via <stack_id>-kubeconfig)
  D->>K: replace CRS <stack_id>-cloud-provider
  D->>K: re-apply server groups, Secret <uuid>, Secret <stack_id>-cloud-provider, autoscaler release
  D->>K: GET+replace Cluster (labels, clusterNetwork, topology incl. new class/version/imageUUID)
  C->>K: KCP rolling replace, then MD rolling replace
  C->>OS: new Nova servers from new image, old ones deleted
  MC->>D: update_cluster_status -> UPDATE_COMPLETE when KCP + MDs + OpenStackMachine image ids match

Sources: magnum-cluster-api:magnum_cluster_api/driver.py:375-436, magnum-cluster-api:src/driver.rs:65-119, magnum-cluster-api:src/driver.rs:312-319, magnum-cluster-api:src/client.rs:73-107. Only kube_tag and image_id are taken from the new template; other label changes are not propagated (magnum-cluster-api:magnum_cluster_api/driver.py:388-396). Because existing MD variables are frozen (§4.3) the per-MD imageUUID override is kept [inferred: worker image change depends on mutate_machine_deployment returning the existing spec unchanged; whether workers get the new image needs verification against CAPI topology semantics].

7.4 Delete

sequenceDiagram
  participant MC as Magnum conductor
  participant D as Driver
  participant K as Mgmt K8s API
  participant C as CAPI / CAPO
  participant OS as Octavia / Neutron / Nova / Keystone
  MC->>D: delete_cluster(cluster)
  D->>OS: Octavia list LBs "Kubernetes .+ from cluster <uuid>", cascade delete, delete VIP FIPs, wait (pre_delete_lb_timeout)
  D->>K: delete CRS+Secret <stack_id>-cloud-provider, CRS+Secret <uuid>
  D->>K: delete Cluster <stack_id>
  D->>K: helm delete <stack_id> (autoscaler)
  D-->>MC: return -> DELETE_IN_PROGRESS
  C->>OS: delete servers, volumes, API LB, network, router, SGs
  loop periodic
    MC->>D: update_cluster_status
    D->>K: Cluster still exists? -> status_reason from events
  end
  D->>OS: Keystone delete app cred <uuid>; Nova delete server groups
  D->>K: delete Secrets cloud-config, ca, etcd, proxy, sa
  D-->>MC: DELETE_COMPLETE (Magnum destroys DB rows)

Sources: magnum-cluster-api:magnum_cluster_api/driver.py:442-465, magnum-cluster-api:magnum_cluster_api/utils.py:359-465, magnum-cluster-api:magnum_cluster_api/driver.py:281-313. Octavia LBs created by the in-cluster CCM (Services of type LoadBalancer) are removed by the driver because CAPO does not know them (magnum-cluster-api:magnum_cluster_api/driver.py:451-455).

8. Errors and logs

Logs: very few. Python: Helm release %s is already in progress / already exists (INFO, swallowed), Helm template %s failed, There is no %s service enabled in the cloud. (magnum-cluster-api:magnum_cluster_api/helm.py:84-87, magnum-cluster-api:magnum_cluster_api/helm.py:152, magnum-cluster-api:magnum_cluster_api/integrations/common.py:49). Rust logs go to stderr via env_logger, default level warn, controlled by RUST_LOG (not oslo.log) (magnum-cluster-api:src/logging.rs:37-45); one debug message on upgrade (magnum-cluster-api:src/driver.rs:83). The user-visible diagnostic channel is status_reason built from Kubernetes Events.

Rust / pyo3 summary: the extension provides (a) Driver: ClusterClass + templates generation from a feature registry (inventory), addon CRS/secret rendering with an embedded Helm templater (crates/helm), immutable-field resolution, failure-domain cleanup; (b) KubeClient: generic dict→DynamicObject create/replace/delete; (c) Monitor: health. Blocking calls release the GIL (Python::detach) and run on a Tokio runtime (magnum-cluster-api:src/driver.rs:187-241, magnum-cluster-api:src/client.rs:52-70).

9. Configuration options

Driver-specific (registered via oslo.config.opts) (magnum-cluster-api:magnum_cluster_api/conf.py:99-126):

Magnum core options consumed: [cinder] default_boot_volume_size (0) and default_boot_volume_type (''), [drivers] verify_ca (True), [kubernetes] keystone_auth_default_policy (/etc/magnum/keystone_auth_default_policy.json), [cluster] pre_delete_lb_timeout (60), [nova_client] endpoint/region (magnum:magnum/conf/cinder.py:40-50, magnum:magnum/conf/drivers.py:19, magnum:magnum/conf/kubernetes.py:19-20, magnum:magnum/conf/cluster.py:35-38, magnum-cluster-api:magnum_cluster_api/clients.py:121-125).

Environment: KUBECONFIG (management cluster), RUST_LOG; proxy: PROXY_PORT, PROXY_BIND, PROXY_ALWAYS (magnum-cluster-api:magnum_cluster_api/proxy/manager.py:44-47, magnum-cluster-api:magnum_cluster_api/proxy/structs.py:51-55). Hard-coded: namespace magnum-system, SSA field manager atmosphere-operator, lock expiry 60 s, server-group cache TTL 300 s on local disk (diskcache) (magnum-cluster-api:magnum_cluster_api/cache.py:12-20).

External requirements:

10. What an OpenKeel Go rewrite must reproduce vs can simplify

Context: OpenKeel already runs on Kubernetes; Nova is backed by KubeVirt, Neutron by OVN/Kube-OVN, Octavia API in neutron-api, Cinder on CSI block storage.

Must reproduce (user-visible contract)

1. Magnum API semantics of the driver: provides tuples for the OS values users already put in templates (ubuntu, ubuntu-focal, debian, flatcar, rockylinux); update_cluster unsupported; control-plane resize allowed only for odd counts; upgrade changes only kube_tag + image of the target template (§2).
2. The status machine of §5 exactly: CAPI Cluster conditions ControlPlaneReady+InfrastructureReady+Ready → *_COMPLETE; nodegroup rules on KCP replicas and MD phase/spec; status_reason built from the latest Events; api_address = https://host:port of controlPlaneEndpoint; coe_version = topology.version; health HEALTHY/UNHEALTHY/UNKNOWN with <machine>.Ready and api keys (tools and Skyline read these).
3. The label catalogue of §4 with the same defaults (pod CIDR 10.100.0.0/16, service CIDR 10.254.0.0/16, auto_healing_enabled=true, keystone_auth_enabled=true, master_lb_floating_ip_enabled=true, boot_volume_*, octavia_*, OIDC, audit, TLS suites, CSI/CCM tags). Unknown labels are silently ignored.
4. Magnum-generated CAs used as kubeadm CAs (secrets <name>-ca/-etcd/-proxy/-sa) so ca-show/ca-sign keep working.
5. Per-cluster application credential lifecycle (create at cluster create, delete after infrastructure is gone) and the cloud.conf for CCM/Cinder CSI/Manila CSI.
6. Pre-delete cleanup of CCM-created Octavia LBs matching Kubernetes .+ from cluster <uuid>.
7. Immutable OpenStackCluster fields (API LB provider/flavor/AZ, disableAPIServerFloatingIP) must not change on later updates.
8. Autoscaler min/max annotations and MHC behaviour (auto_healing_enabled).

Can simplify

• Drop pykube + Python/Rust split: one Go controller using controller-runtime and the upstream CAPI/CAPO Go types; no GIL/eventlet workarounds (magnum-cluster-api:magnum_cluster_api/utils.py:63-91, magnum-cluster-api:src/logging.rs:1-45), no tpool.
• Watch instead of poll: an informer on Cluster, KubeadmControlPlane, MachineDeployment, Machine can update Magnum status immediately, replacing sync_cluster_status polling and the sherlock lock (use the Magnum DB row lock or a Lease per cluster).
• Management cluster = OpenKeel's own cluster: no separate kubeconfig, no magnum-cluster-api-proxy/HAProxy-in-netns (OpenKeel pods can reach tenant networks through OVN/Kube-OVN or a Service) [inferred: depends on OpenKeel tenant-network reachability design].
• Infrastructure provider choice: CAPO against OpenKeel's Nova/Neutron/Octavia/Cinder APIs (zero-change compatibility, CAPO only needs the OpenStack API) vs. CAPK (Cluster API Provider KubeVirt) directly on KubeVirt (fewer hops, but loses Nova server groups, Octavia API LB, Cinder root volumes and the OpenStackMachine image/flavor checks in §5.2 — status logic would need re-mapping). Recommendation: keep CAPO first for behavioural parity [inferred].
• No Helm binary: render addon manifests in-process (Go helm.sh/helm/v3 engine or pre-rendered embedded YAML) and deploy the autoscaler as a plain Deployment.
• Drop legacy paths: the legacy CRS <uuid> vs <stack_id>-cloud-provider split, Calico manifest zoo (18 versions), legacy CCM/CSI cleanup on upgrade, failureDomain: "" cleanup, disableAPIServerFloatingIPManaged, ubuntu-focal — all exist only for upgrades from older driver releases.
• Single ClusterClass per OpenKeel release is a good pattern to keep; versioned name makes upgrades a topology.class switch.
• No Memcached/Redis: the driver's only cache is a local diskcache for server-group ids (magnum-cluster-api:magnum_cluster_api/cache.py:4-20) — replace with an in-process map or none.

11. Blind spots / [inferred]

• Magnum 2026.2 + heatclient: the driver still imports heatclient.exc (magnum-cluster-api:magnum_cluster_api/driver.py:18) and relies on its own python-heatclient dependency (magnum-cluster-api:pyproject.toml:44); Magnum 2026.2's nodegroup_delete no longer special-cases HTTPNotFound (magnum:magnum/conductor/handlers/nodegroup_conductor.py:121-131), so deleting a nodegroup whose MD is already gone ends in DELETE_FAILED instead of row deletion: Magnum commit 31b84327db88 removed the HTTPNotFound special case (06 § 21). Not run.
• needs_trust = False (magnum-cluster-api:magnum_cluster_api/driver.py:47) is not read anywhere in Magnum 2026.2 core (grep found no consumer); whether 2026.2 still creates trusts for this driver was not traced.
• kube_tag default mismatch: Python defaults to v1.25.3 (magnum-cluster-api:magnum_cluster_api/utils.py:228-229) while the Rust ClusterLabels.kube_tag has no pyo3 default (magnum-cluster-api:src/magnum.rs:108-110); a cluster without the label likely fails Rust extraction — not executed.
• _get_cluster_status_reason may raise OpenStackClusterNotCreated before CAPO creates the OpenStackCluster (magnum-cluster-api:magnum_cluster_api/driver.py:153, magnum-cluster-api:magnum_cluster_api/objects.py:255-256); impact on the periodic sync not verified.
• Sherlock's Kubernetes lock object kind (Lease vs. custom) not checked (library not installed locally).
• Upgrade of worker images: depends on CAPI topology propagation of the top-level imageUUID vs. per-MD overrides frozen by mutate_machine_deployment (§7.3); not traced in CAPI.
• Exact rendered contents of Cilium/OCCM/CSI charts (values beyond those cited) were not reviewed line by line; Flatcar Ignition patches and volume partition layouts summarised from patch paths only.
• docs/user/configs.md documents [auto_scaling] v1_22_image…v1_27_image options that no longer exist in conf.py (magnum-cluster-api:docs/user/configs.md:15-49 vs magnum-cluster-api:magnum_cluster_api/conf.py:31-37): doc drift.
• CI versions (CAPI v1.13.2, CAPO v0.14.4) are what the project tests with; no hard version constraint is enforced at runtime.
• The magnum-cluster-api-image-builder CLI (magnum-cluster-api:pyproject.toml:65) was not analysed.

Source: reverse-spec-magnum/08-driver-magnum-cluster-api_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.