# openstack/magnum architecture

> Architecture diagram of the GitHub repository openstack/magnum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openstack/magnum
- Repository: https://github.com/openstack/magnum

## Overview

Magnum is an OpenStack service for provisioning and managing container-orchestration clusters as OpenStack resources. Users enter through its WSGI/Pecan API; resource controllers expose cluster and related operations, while the broader service includes conductor handlers, pluggable drivers, certificate management, persistence, and periodic status/health work. The excerpts show service-health and certificate paths in detail, but not the API-to-conductor RPC dispatch or most cluster-operation implementations; those connections are therefore omitted. Several documented-by-product subsystems are represented by their exact source directories where their implementation was not sampled.

Main entry points: [`magnum/drivers/common/driver.py`](https://github.com/openstack/magnum/blob/master/magnum/drivers/common/driver.py) (Cluster drivers), [`magnum/api/controllers/v1/magnum_services.py`](https://github.com/openstack/magnum/blob/master/magnum/api/controllers/v1/magnum_services.py) (Service controller), [`magnum/api/app.py`](https://github.com/openstack/magnum/blob/master/magnum/api/app.py) (WSGI application), [`magnum/common/cert_manager`](https://github.com/openstack/magnum/tree/master/magnum/common/cert_manager) (Certificate backends)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and resources"]
  node_wsgi["WSGI application<br/>[app.py]"]
  node_controllers["REST controllers"]
  node_service_controller["Service controller<br/>[magnum_services.py]"]
  node_cluster_templates["Cluster templates"]
end

subgraph group_control["Cluster control"]
  node_conductor["Conductor handlers"]
  node_drivers["Cluster drivers<br/>[driver.py]"]
  node_scale["Scale manager<br/>[scale_manager.py]"]
  node_rpc["RPC transport<br/>[rpc.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_context["Request context<br/>[context.py]"]
  node_policy["Authorization policy<br/>[policy.py]"]
  node_profiler["Request profiling<br/>[profiler.py]"]
  node_exceptions["Service exceptions<br/>[exception.py]"]
  node_i18n["Translations<br/>[i18n.py]"]
end

subgraph group_security["Certificates and security"]
  node_cert_workflow["Cluster certificate workflow<br/>[cert_manager.py]"]
  node_cert_backend["Certificate backends"]
  node_cert_core["Certificate interface<br/>[cert_manager.py]"]
  node_x509["X.509 operations<br/>[operations.py]"]
end

subgraph group_state["Persistence and operations"]
  node_objects["Resource objects"]
  node_object_base["Object base<br/>[base.py]"]
  node_db_api["Database API<br/>[api.py]"]
  node_database[("SQL database<br/>[api.py]")]
  node_periodic["Cluster periodic tasks<br/>[periodic.py]"]
  node_service_periodic["Service heartbeat"]
  node_service_object["Service records<br/>[magnum_service.py]"]
  node_servicegroup["Service health<br/>[servicegroup.py]"]
end

node_user(("OpenStack user"))
node_cloud["OpenStack cloud services"]
node_barbican[("Barbican key manager")]

node_user -.->|"sends requests"| node_wsgi
node_wsgi -.->|"serves API"| node_controllers
node_wsgi -->|"sets defaults"| node_config
node_service_controller -->|"lists services"| node_objects
node_service_controller -->|"checks liveness"| node_servicegroup
node_service_controller -->|"enforces access"| node_policy
node_objects -->|"exports object types"| node_object_base
node_service_object -->|"reads and writes"| node_db_api
node_service_periodic -->|"reports heartbeat"| node_service_object
node_service_periodic -->|"sets task context"| node_periodic
node_periodic -->|"updates cluster status"| node_drivers
node_periodic -->|"polls cluster monitors"| node_conductor
node_scale -->|"selects scale manager"| node_drivers
node_scale -->|"loads cluster state"| node_objects
node_cert_workflow -->|"stores certificates"| node_cert_backend
node_cert_backend -->|"implements interface"| node_cert_core
node_cert_core -->|"uses operations"| node_x509
node_cert_backend -.->|"stores secrets"| node_barbican
node_drivers -->|"uses template model"| node_cluster_templates
node_conductor -.->|"dispatches operations"| node_rpc
node_rpc -.->|"routes operations"| node_conductor
node_drivers -.->|"provisions infrastructure"| node_cloud
node_db_api -.->|"persists records"| node_database

click node_wsgi "https://github.com/openstack/magnum/blob/master/magnum/api/app.py"
click node_controllers "https://github.com/openstack/magnum/tree/master/magnum/api/controllers"
click node_service_controller "https://github.com/openstack/magnum/blob/master/magnum/api/controllers/v1/magnum_services.py"
click node_objects "https://github.com/openstack/magnum/tree/master/magnum/objects"
click node_object_base "https://github.com/openstack/magnum/blob/master/magnum/objects/base.py"
click node_cluster_templates "https://github.com/openstack/magnum/blob/master/magnum/objects/cluster_template.py"
click node_db_api "https://github.com/openstack/magnum/blob/master/magnum/db/api.py"
click node_database "https://github.com/openstack/magnum/blob/master/magnum/db/sqlalchemy/api.py"
click node_conductor "https://github.com/openstack/magnum/tree/master/magnum/conductor/handlers"
click node_drivers "https://github.com/openstack/magnum/blob/master/magnum/drivers/common/driver.py"
click node_scale "https://github.com/openstack/magnum/blob/master/magnum/conductor/scale_manager.py"
click node_periodic "https://github.com/openstack/magnum/blob/master/magnum/service/periodic.py"
click node_service_periodic "https://github.com/openstack/magnum/blob/master/magnum/servicegroup/magnum_service_periodic.py"
click node_service_object "https://github.com/openstack/magnum/blob/master/magnum/objects/magnum_service.py"
click node_servicegroup "https://github.com/openstack/magnum/blob/master/magnum/api/servicegroup.py"
click node_rpc "https://github.com/openstack/magnum/blob/master/magnum/common/rpc.py"
click node_cert_workflow "https://github.com/openstack/magnum/blob/master/magnum/conductor/handlers/common/cert_manager.py"
click node_cert_backend "https://github.com/openstack/magnum/tree/master/magnum/common/cert_manager"
click node_cert_core "https://github.com/openstack/magnum/blob/master/magnum/common/cert_manager/cert_manager.py"
click node_x509 "https://github.com/openstack/magnum/blob/master/magnum/common/x509/operations.py"
click node_config "https://github.com/openstack/magnum/blob/master/magnum/common/config.py"
click node_context "https://github.com/openstack/magnum/blob/master/magnum/common/context.py"
click node_policy "https://github.com/openstack/magnum/blob/master/magnum/common/policy.py"
click node_profiler "https://github.com/openstack/magnum/blob/master/magnum/common/profiler.py"
click node_exceptions "https://github.com/openstack/magnum/blob/master/magnum/common/exception.py"
click node_i18n "https://github.com/openstack/magnum/blob/master/magnum/i18n.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_wsgi,node_controllers,node_service_controller,node_cluster_templates,node_user toneBlue
class node_conductor,node_drivers,node_scale,node_rpc,node_config,node_context,node_policy,node_profiler,node_exceptions,node_i18n,node_barbican toneAmber
class node_cert_workflow,node_cert_backend,node_cert_core,node_x509 toneMint
class node_objects,node_object_base,node_db_api,node_database,node_periodic,node_service_periodic,node_service_object,node_servicegroup toneRose
class node_cloud toneIndigo
```

## Components

### API and resources

- [WSGI application](https://github.com/openstack/magnum/blob/master/magnum/api/app.py): `magnum/api/app.py`
- [REST controllers](https://github.com/openstack/magnum/tree/master/magnum/api/controllers): `magnum/api/controllers`
- [Service controller](https://github.com/openstack/magnum/blob/master/magnum/api/controllers/v1/magnum_services.py): `magnum/api/controllers/v1/magnum_services.py`
- [Cluster templates](https://github.com/openstack/magnum/blob/master/magnum/objects/cluster_template.py): `magnum/objects/cluster_template.py`

### Cluster control

- [Conductor handlers](https://github.com/openstack/magnum/tree/master/magnum/conductor/handlers): `magnum/conductor/handlers`
- [Cluster drivers](https://github.com/openstack/magnum/blob/master/magnum/drivers/common/driver.py): `magnum/drivers/common/driver.py`
- [Scale manager](https://github.com/openstack/magnum/blob/master/magnum/conductor/scale_manager.py): `magnum/conductor/scale_manager.py`
- [RPC transport](https://github.com/openstack/magnum/blob/master/magnum/common/rpc.py): `magnum/common/rpc.py`
- [Configuration](https://github.com/openstack/magnum/blob/master/magnum/common/config.py): `magnum/common/config.py`
- [Request context](https://github.com/openstack/magnum/blob/master/magnum/common/context.py): `magnum/common/context.py`
- [Authorization policy](https://github.com/openstack/magnum/blob/master/magnum/common/policy.py): `magnum/common/policy.py`
- [Request profiling](https://github.com/openstack/magnum/blob/master/magnum/common/profiler.py): `magnum/common/profiler.py`
- [Service exceptions](https://github.com/openstack/magnum/blob/master/magnum/common/exception.py): `magnum/common/exception.py`
- [Translations](https://github.com/openstack/magnum/blob/master/magnum/i18n.py): `magnum/i18n.py`

### Certificates and security

- [Cluster certificate workflow](https://github.com/openstack/magnum/blob/master/magnum/conductor/handlers/common/cert_manager.py): `magnum/conductor/handlers/common/cert_manager.py`
- [Certificate backends](https://github.com/openstack/magnum/tree/master/magnum/common/cert_manager): `magnum/common/cert_manager`
- [Certificate interface](https://github.com/openstack/magnum/blob/master/magnum/common/cert_manager/cert_manager.py): `magnum/common/cert_manager/cert_manager.py`
- [X.509 operations](https://github.com/openstack/magnum/blob/master/magnum/common/x509/operations.py): `magnum/common/x509/operations.py`

### Persistence and operations

- [Resource objects](https://github.com/openstack/magnum/tree/master/magnum/objects): `magnum/objects`
- [Object base](https://github.com/openstack/magnum/blob/master/magnum/objects/base.py): `magnum/objects/base.py`
- [Database API](https://github.com/openstack/magnum/blob/master/magnum/db/api.py): `magnum/db/api.py`
- [SQL database](https://github.com/openstack/magnum/blob/master/magnum/db/sqlalchemy/api.py): `magnum/db/sqlalchemy/api.py`
- [Cluster periodic tasks](https://github.com/openstack/magnum/blob/master/magnum/service/periodic.py): `magnum/service/periodic.py`
- [Service heartbeat](https://github.com/openstack/magnum/blob/master/magnum/servicegroup/magnum_service_periodic.py): `magnum/servicegroup/magnum_service_periodic.py`
- [Service records](https://github.com/openstack/magnum/blob/master/magnum/objects/magnum_service.py): `magnum/objects/magnum_service.py`
- [Service health](https://github.com/openstack/magnum/blob/master/magnum/api/servicegroup.py): `magnum/api/servicegroup.py`

### Other components

- **OpenStack user**
- **OpenStack cloud services**
- **Barbican key manager**

## Connections

- OpenStack user → WSGI application: sends requests
- WSGI application → REST controllers: serves API
- WSGI application → Configuration: sets defaults (evidence: `magnum/api/app.py`)
- Service controller → Resource objects: lists services (evidence: `magnum/api/controllers/v1/magnum_services.py`)
- Service controller → Service health: checks liveness (evidence: `magnum/api/controllers/v1/magnum_services.py`)
- Service controller → Authorization policy: enforces access (evidence: `magnum/api/controllers/v1/magnum_services.py`)
- Resource objects → Object base: exports object types (evidence: `magnum/objects/__init__.py`)
- Service records → Database API: reads and writes (evidence: `magnum/objects/magnum_service.py`)
- Service heartbeat → Service records: reports heartbeat (evidence: `magnum/servicegroup/magnum_service_periodic.py`)
- Service heartbeat → Cluster periodic tasks: sets task context (evidence: `magnum/servicegroup/magnum_service_periodic.py`)
- Cluster periodic tasks → Cluster drivers: updates cluster status (evidence: `magnum/service/periodic.py`)
- Cluster periodic tasks → Conductor handlers: polls cluster monitors (evidence: `magnum/service/periodic.py`)
- Scale manager → Cluster drivers: selects scale manager (evidence: `magnum/conductor/scale_manager.py`)
- Scale manager → Resource objects: loads cluster state (evidence: `magnum/conductor/scale_manager.py`)
- Cluster certificate workflow → Certificate backends: stores certificates (evidence: `magnum/conductor/handlers/common/cert_manager.py`)
- Certificate backends → Certificate interface: implements interface (evidence: `magnum/common/cert_manager/barbican_cert_manager.py`)
- Certificate interface → X.509 operations: uses operations (evidence: `magnum/common/cert_manager/cert_manager.py`)
- Certificate backends → Barbican key manager: stores secrets (evidence: `magnum/common/cert_manager/barbican_cert_manager.py`)
- Cluster drivers → Cluster templates: uses template model (evidence: `magnum/drivers/common/driver.py`)
- Conductor handlers → RPC transport: dispatches operations
- RPC transport → Conductor handlers: routes operations
- Cluster drivers → OpenStack cloud services: provisions infrastructure
- Database API → SQL database: persists records
