# ceph/ceph-csi architecture

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

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

## Overview

Ceph CSI is a Kubernetes-facing storage driver suite that translates CSI requests into Ceph-backed volume operations. The principal workflow runs from a container orchestrator request through a driver/controller to volume provisioning, then through node staging and mounting for workload use. RBD provides block and filesystem-mode volumes; CephFS and NFS provide shared-file options, while NVMe-oF exposes RBD-backed volumes through gateways. Snapshots, group snapshots, replication, health checking, and key management are additional capabilities. The graph reflects the README and supplied excerpts; several subsystem connections are documented capabilities or inferred from explicit delegation, while unsampled implementation details are omitted.

Main entry points: [`cmd/cephcsi.go`](https://github.com/ceph/ceph-csi/blob/devel/cmd/cephcsi.go) (CSI process), [`internal/rbd/controllerserver.go`](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/controllerserver.go) (RBD controller), [`internal/nvmeof/controller/controllerserver.go`](https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/controller/controllerserver.go) (NVMe-oF controller), [`internal/cephfs/controllerserver.go`](https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/controllerserver.go) (CephFS controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_iface["CSI interface"]
  node_entry["CSI process<br/>[cephcsi.go]"]
  node_common["CSI common servers<br/>[server.go]"]
end

subgraph group_block["RBD and NVMe-oF"]
  node_rbd_driver["RBD driver<br/>[driver.go]"]
  node_rbd_controller["RBD controller"]
  node_rbd_node["RBD node service<br/>[nodeserver.go]"]
  node_rbd_manager["RBD manager<br/>[manager.go]"]
  node_rbd_group["RBD groups"]
  node_nvme_driver["NVMe-oF driver<br/>[driver.go]"]
  node_nvme_controller["NVMe-oF controller"]
  node_nvme_node["NVMe-oF node service<br/>[nodeserver.go]"]
end

subgraph group_files["CephFS and NFS"]
  node_cephfs_driver["CephFS driver<br/>[driver.go]"]
  node_cephfs_controller["CephFS controller"]
  node_cephfs_node["CephFS node service<br/>[nodeserver.go]"]
  node_cephfs_core["CephFS operations<br/>[volume.go]"]
  node_nfs_controller["NFS controller"]
  node_nfs_node["NFS node service<br/>[nodeserver.go]"]
end

subgraph group_extensions["Operations and extensions"]
  node_journal[("RADOS journals<br/>[voljournal.go]")]
  node_deploy_manifests["Driver deployment resources<br/>[doc.go]"]
  node_addons["CSI add-on services<br/>[server.go]"]
  node_replication["RBD replication<br/>[replication.go]"]
  node_kms["Key management<br/>[kms.go]"]
  node_health["Volume health checks<br/>[manager.go]"]
end

node_orchestrator(("Container orchestrator"))
node_gateway["NVMe-oF gateway"]
node_ceph_cluster[("Ceph cluster")]
node_kubernetes["Kubernetes API"]

node_orchestrator -->|"sends CSI requests"| node_entry
node_entry -->|"starts driver"| node_rbd_driver
node_entry -->|"starts driver"| node_cephfs_driver
node_entry -->|"starts driver"| node_nvme_driver
node_entry -->|"uses shared servers"| node_common
node_rbd_driver -->|"registers controller"| node_rbd_controller
node_rbd_driver -->|"registers node service"| node_rbd_node
node_rbd_controller -->|"manages volumes"| node_rbd_manager
node_rbd_controller -->|"creates and deletes images"| node_ceph_cluster
node_rbd_manager -->|"records volume groups"| node_journal
node_rbd_group -->|"manages group snapshots"| node_rbd_manager
node_rbd_node -->|"attaches volumes"| node_ceph_cluster
node_cephfs_driver -->|"registers controller"| node_cephfs_controller
node_cephfs_driver -->|"registers node service"| node_cephfs_node
node_cephfs_controller -->|"creates volumes and snapshots"| node_cephfs_core
node_cephfs_core -->|"operates on subvolumes"| node_ceph_cluster
node_cephfs_controller -->|"tracks volume state"| node_journal
node_cephfs_node -->|"mounts CephFS"| node_ceph_cluster
node_nfs_controller -->|"delegates backend operations"| node_cephfs_controller
node_nfs_controller -->|"creates NFS exports"| node_ceph_cluster
node_nfs_node -->|"mounts exported volumes"| node_ceph_cluster
node_nvme_driver -->|"registers controller"| node_nvme_controller
node_nvme_driver -->|"registers node service"| node_nvme_node
node_nvme_controller -->|"forwards RBD operations"| node_rbd_controller
node_nvme_controller -->|"configures subsystems and hosts"| node_gateway
node_nvme_node -->|"connects to namespaces"| node_gateway
node_nvme_controller -->|"provisions RBD backing"| node_ceph_cluster
node_orchestrator -->|"manages deployment"| node_kubernetes
node_deploy_manifests -->|"defines driver resources"| node_kubernetes
node_entry -.->|"serves add-on APIs"| node_addons
node_addons -.->|"dispatches replication"| node_replication
node_replication -.->|"manages replicated volumes"| node_ceph_cluster
node_rbd_controller -.->|"uses encryption keys"| node_kms
node_rbd_node -.->|"checks volume health"| node_health
node_cephfs_node -.->|"checks volume health"| node_health

click node_entry "https://github.com/ceph/ceph-csi/blob/devel/cmd/cephcsi.go"
click node_common "https://github.com/ceph/ceph-csi/blob/devel/internal/csi-common/server.go"
click node_rbd_driver "https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/driver/driver.go"
click node_rbd_controller "https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/controllerserver.go"
click node_rbd_node "https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/nodeserver.go"
click node_rbd_manager "https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/manager.go"
click node_rbd_group "https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/group_controllerserver.go"
click node_nvme_driver "https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/driver/driver.go"
click node_nvme_controller "https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/controller/controllerserver.go"
click node_nvme_node "https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/nodeserver/nodeserver.go"
click node_cephfs_driver "https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/driver.go"
click node_cephfs_controller "https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/controllerserver.go"
click node_cephfs_node "https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/nodeserver.go"
click node_cephfs_core "https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/core/volume.go"
click node_nfs_controller "https://github.com/ceph/ceph-csi/blob/devel/internal/nfs/controller/controllerserver.go"
click node_nfs_node "https://github.com/ceph/ceph-csi/blob/devel/internal/nfs/nodeserver/nodeserver.go"
click node_journal "https://github.com/ceph/ceph-csi/blob/devel/internal/journal/voljournal.go"
click node_deploy_manifests "https://github.com/ceph/ceph-csi/blob/devel/api/deploy/kubernetes/doc.go"
click node_addons "https://github.com/ceph/ceph-csi/blob/devel/internal/csi-addons/server/server.go"
click node_replication "https://github.com/ceph/ceph-csi/blob/devel/internal/csi-addons/rbd/replication.go"
click node_kms "https://github.com/ceph/ceph-csi/blob/devel/internal/kms/kms.go"
click node_health "https://github.com/ceph/ceph-csi/blob/devel/internal/health-checker/manager.go"

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_entry,node_common toneBlue
class node_rbd_driver,node_rbd_controller,node_rbd_node,node_rbd_manager,node_rbd_group,node_nvme_driver,node_nvme_controller,node_nvme_node,node_ceph_cluster toneAmber
class node_cephfs_driver,node_cephfs_controller,node_cephfs_node,node_cephfs_core,node_nfs_controller,node_nfs_node,node_kubernetes toneMint
class node_journal,node_deploy_manifests,node_addons,node_replication,node_kms,node_health toneRose
class node_orchestrator,node_gateway toneIndigo
```

## Components

### CSI interface

- [CSI process](https://github.com/ceph/ceph-csi/blob/devel/cmd/cephcsi.go): `cmd/cephcsi.go`
- [CSI common servers](https://github.com/ceph/ceph-csi/blob/devel/internal/csi-common/server.go): `internal/csi-common/server.go`

### RBD and NVMe-oF

- [RBD driver](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/driver/driver.go): `internal/rbd/driver/driver.go`
- [RBD controller](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/controllerserver.go): `internal/rbd/controllerserver.go`
- [RBD node service](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/nodeserver.go): `internal/rbd/nodeserver.go`
- [RBD manager](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/manager.go): `internal/rbd/manager.go`
- [RBD groups](https://github.com/ceph/ceph-csi/blob/devel/internal/rbd/group_controllerserver.go): `internal/rbd/group_controllerserver.go`
- [NVMe-oF driver](https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/driver/driver.go): `internal/nvmeof/driver/driver.go`
- [NVMe-oF controller](https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/controller/controllerserver.go): `internal/nvmeof/controller/controllerserver.go`
- [NVMe-oF node service](https://github.com/ceph/ceph-csi/blob/devel/internal/nvmeof/nodeserver/nodeserver.go): `internal/nvmeof/nodeserver/nodeserver.go`

### CephFS and NFS

- [CephFS driver](https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/driver.go): `internal/cephfs/driver.go`
- [CephFS controller](https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/controllerserver.go): `internal/cephfs/controllerserver.go`
- [CephFS node service](https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/nodeserver.go): `internal/cephfs/nodeserver.go`
- [CephFS operations](https://github.com/ceph/ceph-csi/blob/devel/internal/cephfs/core/volume.go): `internal/cephfs/core/volume.go`
- [NFS controller](https://github.com/ceph/ceph-csi/blob/devel/internal/nfs/controller/controllerserver.go): `internal/nfs/controller/controllerserver.go`
- [NFS node service](https://github.com/ceph/ceph-csi/blob/devel/internal/nfs/nodeserver/nodeserver.go): `internal/nfs/nodeserver/nodeserver.go`

### Operations and extensions

- [RADOS journals](https://github.com/ceph/ceph-csi/blob/devel/internal/journal/voljournal.go): `internal/journal/voljournal.go`
- [Driver deployment resources](https://github.com/ceph/ceph-csi/blob/devel/api/deploy/kubernetes/doc.go): `api/deploy/kubernetes/doc.go`
- [CSI add-on services](https://github.com/ceph/ceph-csi/blob/devel/internal/csi-addons/server/server.go): `internal/csi-addons/server/server.go`
- [RBD replication](https://github.com/ceph/ceph-csi/blob/devel/internal/csi-addons/rbd/replication.go): `internal/csi-addons/rbd/replication.go`
- [Key management](https://github.com/ceph/ceph-csi/blob/devel/internal/kms/kms.go): `internal/kms/kms.go`
- [Volume health checks](https://github.com/ceph/ceph-csi/blob/devel/internal/health-checker/manager.go): `internal/health-checker/manager.go`

### Other components

- **Container orchestrator**
- **NVMe-oF gateway**
- **Ceph cluster**
- **Kubernetes API**

## Connections

- Container orchestrator → CSI process: sends CSI requests
- CSI process → RBD driver: starts driver
- CSI process → CephFS driver: starts driver
- CSI process → NVMe-oF driver: starts driver
- CSI process → CSI common servers: uses shared servers
- RBD driver → RBD controller: registers controller
- RBD driver → RBD node service: registers node service
- RBD controller → RBD manager: manages volumes
- RBD controller → Ceph cluster: creates and deletes images
- RBD manager → RADOS journals: records volume groups
- RBD groups → RBD manager: manages group snapshots
- RBD node service → Ceph cluster: attaches volumes
- CephFS driver → CephFS controller: registers controller
- CephFS driver → CephFS node service: registers node service
- CephFS controller → CephFS operations: creates volumes and snapshots
- CephFS operations → Ceph cluster: operates on subvolumes
- CephFS controller → RADOS journals: tracks volume state
- CephFS node service → Ceph cluster: mounts CephFS
- NFS controller → CephFS controller: delegates backend operations
- NFS controller → Ceph cluster: creates NFS exports
- NFS node service → Ceph cluster: mounts exported volumes
- NVMe-oF driver → NVMe-oF controller: registers controller
- NVMe-oF driver → NVMe-oF node service: registers node service
- NVMe-oF controller → RBD controller: forwards RBD operations
- NVMe-oF controller → NVMe-oF gateway: configures subsystems and hosts
- NVMe-oF node service → NVMe-oF gateway: connects to namespaces
- NVMe-oF controller → Ceph cluster: provisions RBD backing
- Container orchestrator → Kubernetes API: manages deployment
- Driver deployment resources → Kubernetes API: defines driver resources
- CSI process → CSI add-on services: serves add-on APIs
- CSI add-on services → RBD replication: dispatches replication
- RBD replication → Ceph cluster: manages replicated volumes
- RBD controller → Key management: uses encryption keys
- RBD node service → Volume health checks: checks volume health
- CephFS node service → Volume health checks: checks volume health