# ceph/calamari architecture

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

- Interactive diagram: https://gitdiagram.com/ceph/calamari
- Repository: https://github.com/ceph/calamari
- Video tour (about a minute): https://gitdiagram.com/ceph/calamari/video

## Overview

Calamari is a Ceph management and monitoring server that exposes a high-level REST API. The main user workflow is to request cluster status or an administrative change through the API; the server exposes cluster, OSD, pool, CRUSH, and request endpoints, while its management service monitors clusters and coordinates remote work. Persistent cluster state and request/event handling support the service. The tree and excerpts establish these components, but do not show all runtime call wiring, so uncertain links are omitted.

Main entry points: [`cthulhu/cthulhu/manager/manager.py`](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/manager.py) (Service manager), [`rest-api/calamari_rest/views/v2.py`](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/v2.py) (Cluster API views), [`cthulhu/cthulhu/manager/rpc.py`](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/rpc.py) (RPC service), [`calamari-web/calamari_web/wsgi.py`](https://github.com/ceph/calamari/blob/master/calamari-web/calamari_web/wsgi.py) (Django web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST interface"]
  node_web["Django web app<br/>[wsgi.py]"]
  node_routes["API routes<br/>[v2.py]"]
  node_views["Cluster API views<br/>[v2.py]"]
  node_serializers["API serializers<br/>[v2.py]"]
  node_dbviews["Database views"]
  node_remoteview["Remote API views<br/>[remote_view_set.py]"]
end

subgraph group_control["Management service"]
  node_manager["Service manager<br/>[manager.py]"]
  node_cluster["Cluster monitor<br/>[cluster_monitor.py]"]
  node_requests["Request handling"]
  node_rpc["RPC service<br/>[rpc.py]"]
end

subgraph group_remote["Ceph integration"]
  node_salt["Salt remote<br/>[salt_remote.py]"]
  node_monremote["Monitor remote<br/>[mon_remote.py]"]
  node_rbd["RBD API<br/>[rbd_api.py]"]
end

subgraph group_state["State and telemetry"]
  node_persister["State persister<br/>[persister.py]"]
  node_models[("Persistence models<br/>[models.py]")]
  node_events["Event manager<br/>[eventer.py]"]
  node_carbon["Metrics cache<br/>[server.py]"]
  node_graphite["Graphite service<br/>[settings.py]"]
end

node_operator(("Operator or UI"))
node_ceph{{"Ceph cluster"}}

node_operator -->|"uses"| node_web
node_web -->|"dispatches"| node_routes
node_routes -->|"routes requests"| node_views
node_views -->|"formats data"| node_serializers
node_views -->|"queries state"| node_dbviews
node_manager -->|"tracks clusters"| node_cluster
node_manager -->|"starts request handling"| node_requests
node_manager -->|"starts RPC"| node_rpc
node_manager -->|"starts persistence"| node_persister
node_manager -->|"starts event handling"| node_events
node_rpc -->|"dispatches remote work"| node_salt
node_salt -->|"runs Ceph jobs"| node_monremote
node_monremote -->|"queries cluster"| node_ceph
node_remoteview -->|"requests remote work"| node_rpc
node_persister -->|"stores state"| node_models
node_dbviews -->|"reads state"| node_models
node_carbon -.->|"serves metrics"| node_graphite
node_rbd -.->|"accesses RBD"| node_ceph

click node_web "https://github.com/ceph/calamari/blob/master/calamari-web/calamari_web/wsgi.py"
click node_routes "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/urls/v2.py"
click node_views "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/v2.py"
click node_serializers "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/serializers/v2.py"
click node_dbviews "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/database_view_set.py"
click node_manager "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/manager.py"
click node_cluster "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/cluster_monitor.py"
click node_requests "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/request_collection.py"
click node_rpc "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/rpc.py"
click node_remoteview "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/remote_view_set.py"
click node_salt "https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/salt_remote.py"
click node_monremote "https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/mon_remote.py"
click node_rbd "https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/rbd_api.py"
click node_persister "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/persistence/persister.py"
click node_models "https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/models.py"
click node_events "https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/eventer.py"
click node_carbon "https://github.com/ceph/calamari/blob/master/calamari-lite/calamari_lite/server.py"
click node_graphite "https://github.com/ceph/calamari/blob/master/calamari-web/calamari_web/settings.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_web,node_routes,node_views,node_serializers,node_dbviews,node_remoteview,node_operator toneBlue
class node_manager,node_cluster,node_requests,node_rpc toneAmber
class node_salt,node_monremote,node_rbd toneMint
class node_persister,node_models,node_events,node_carbon,node_graphite toneRose
class node_ceph toneIndigo
```

## Components

### REST interface

- [Django web app](https://github.com/ceph/calamari/blob/master/calamari-web/calamari_web/wsgi.py): `calamari-web/calamari_web/wsgi.py`
- [API routes](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/urls/v2.py): `rest-api/calamari_rest/urls/v2.py`
- [Cluster API views](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/v2.py): `rest-api/calamari_rest/views/v2.py`
- [API serializers](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/serializers/v2.py): `rest-api/calamari_rest/serializers/v2.py`
- [Database views](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/database_view_set.py): `rest-api/calamari_rest/views/database_view_set.py`
- [Remote API views](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/views/remote_view_set.py): `rest-api/calamari_rest/views/remote_view_set.py`

### Management service

- [Service manager](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/manager.py): `cthulhu/cthulhu/manager/manager.py`
- [Cluster monitor](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/cluster_monitor.py): `cthulhu/cthulhu/manager/cluster_monitor.py`
- [Request handling](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/request_collection.py): `cthulhu/cthulhu/manager/request_collection.py`
- [RPC service](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/rpc.py): `cthulhu/cthulhu/manager/rpc.py`

### Ceph integration

- [Salt remote](https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/salt_remote.py): `calamari-common/calamari_common/remote/salt_remote.py`
- [Monitor remote](https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/mon_remote.py): `calamari-common/calamari_common/remote/mon_remote.py`
- [RBD API](https://github.com/ceph/calamari/blob/master/calamari-common/calamari_common/remote/rbd_api.py): `calamari-common/calamari_common/remote/rbd_api.py`

### State and telemetry

- [State persister](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/persistence/persister.py): `cthulhu/cthulhu/persistence/persister.py`
- [Persistence models](https://github.com/ceph/calamari/blob/master/rest-api/calamari_rest/models.py): `rest-api/calamari_rest/models.py`
- [Event manager](https://github.com/ceph/calamari/blob/master/cthulhu/cthulhu/manager/eventer.py): `cthulhu/cthulhu/manager/eventer.py`
- [Metrics cache](https://github.com/ceph/calamari/blob/master/calamari-lite/calamari_lite/server.py): `calamari-lite/calamari_lite/server.py`
- [Graphite service](https://github.com/ceph/calamari/blob/master/calamari-web/calamari_web/settings.py): `calamari-web/calamari_web/settings.py`

### Other components

- **Operator or UI**
- **Ceph cluster**

## Connections

- Operator or UI → Django web app: uses
- Django web app → API routes: dispatches
- API routes → Cluster API views: routes requests
- Cluster API views → API serializers: formats data
- Cluster API views → Database views: queries state
- Service manager → Cluster monitor: tracks clusters
- Service manager → Request handling: starts request handling
- Service manager → RPC service: starts RPC
- Service manager → State persister: starts persistence
- Service manager → Event manager: starts event handling
- RPC service → Salt remote: dispatches remote work
- Salt remote → Monitor remote: runs Ceph jobs
- Monitor remote → Ceph cluster: queries cluster
- Remote API views → RPC service: requests remote work
- State persister → Persistence models: stores state
- Database views → Persistence models: reads state
- Metrics cache → Graphite service: serves metrics
- RBD API → Ceph cluster: accesses RBD