# vitalif/vitastor architecture

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

- Interactive diagram: https://gitdiagram.com/vitalif/vitastor
- Repository: https://github.com/vitalif/vitastor

## Overview

Vitastor is distributed block, file, and object storage. Users provision and administer pools, images, and disks through the CLI, while clients and protocol adapters expose stored data to workloads; OSDs replicate data and persist it on disk. The monitor distributes cluster and placement state, with etcd as the state store. The README documents QEMU, UBLK, NBD, NFS, OpenStack, OpenNebula, Proxmox, and Kubernetes integrations. Sampled source confirms core client, etcd-state, CSI, and NFS-KV behavior; some documented integration wiring is represented only at the subsystem level.

Main entry points: [`src/client/cluster_client.cpp`](https://github.com/vitalif/vitastor/blob/master/src/client/cluster_client.cpp) (Cluster client), [`src/cmd/cli.cpp`](https://github.com/vitalif/vitastor/blob/master/src/cmd/cli.cpp) (Vitastor CLI), [`src/nfs/nfs_proxy.cpp`](https://github.com/vitalif/vitastor/blob/master/src/nfs/nfs_proxy.cpp) (NFS service), [`mon/mon.js`](https://github.com/vitalif/vitastor/blob/master/mon/mon.js) (Monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Administration"]
  node_cli["Vitastor CLI<br/>[cli.cpp]"]
  node_disktool["Disk management<br/>[disk_tool.cpp]"]
end

subgraph group_control["Cluster control"]
  node_monitor["Monitor<br/>[mon.js]"]
  node_monhttp["Monitor HTTP<br/>[http_server.js]"]
  node_stateclient["State client"]
  node_placement["PG placement<br/>[pg_gen.js]"]
end

subgraph group_data["Storage data plane"]
  node_clusterclient["Cluster client<br/>[cluster_client.cpp]"]
  node_messenger["OSD messaging<br/>[messenger.cpp]"]
  node_osd["OSD<br/>[osd.cpp]"]
  node_blockstore["Blockstore<br/>[blockstore.cpp]"]
  node_disk[("OSD disk")]
end

subgraph group_interfaces["Workload interfaces"]
  node_qemu["QEMU interface<br/>[qemu_driver.c]"]
  node_ublk["UBLK interface<br/>[ublk_server.cpp]"]
  node_nbd["NBD interface<br/>[nbd_proxy.cpp]"]
  node_nfs["NFS service<br/>[nfs_proxy.cpp]"]
  node_kv["Vitastor KV<br/>[kv_db.cpp]"]
end

subgraph group_integrations["Platform integrations"]
  node_csi["Kubernetes CSI"]
  node_nodebinding["Node binding<br/>[client.cc]"]
  node_openstack["OpenStack driver<br/>[cinder-vitastor.py]"]
  node_opennebula["OpenNebula driver<br/>[patch-oned-conf.py]"]
end

node_operator(("Operator"))
node_workload(("Workload"))
node_etcd[("etcd state")]

node_operator -->|"administers"| node_cli
node_operator -->|"prepares disks"| node_disktool
node_cli -->|"requests cluster operations"| node_monhttp
node_monitor -->|"stores cluster state"| node_etcd
node_stateclient -->|"reads cluster state"| node_etcd
node_monitor -->|"generates placement"| node_placement
node_clusterclient -->|"loads state"| node_stateclient
node_clusterclient -->|"dispatches I/O"| node_messenger
node_messenger -->|"sends OSD requests"| node_osd
node_osd -->|"executes storage operations"| node_blockstore
node_blockstore -->|"reads and writes"| node_disk
node_workload -->|"uses"| node_qemu
node_workload -->|"uses"| node_ublk
node_workload -->|"uses"| node_nbd
node_workload -->|"mounts"| node_nfs
node_qemu -->|"submits I/O"| node_clusterclient
node_ublk -->|"submits I/O"| node_clusterclient
node_nbd -->|"submits I/O"| node_clusterclient
node_nfs -->|"serves KV filesystem"| node_kv
node_nfs -->|"accesses shared data"| node_clusterclient
node_csi -->|"invokes volume operations"| node_cli
node_nodebinding -->|"uses client API"| node_clusterclient
node_openstack -.->|"integrates provisioning"| node_cli
node_opennebula -.->|"integrates provisioning"| node_cli

click node_cli "https://github.com/vitalif/vitastor/blob/master/src/cmd/cli.cpp"
click node_disktool "https://github.com/vitalif/vitastor/blob/master/src/disk_tool/disk_tool.cpp"
click node_monitor "https://github.com/vitalif/vitastor/blob/master/mon/mon.js"
click node_monhttp "https://github.com/vitalif/vitastor/blob/master/mon/http_server.js"
click node_stateclient "https://github.com/vitalif/vitastor/blob/master/src/client/etcd_state_client.cpp"
click node_placement "https://github.com/vitalif/vitastor/blob/master/mon/pg_gen.js"
click node_clusterclient "https://github.com/vitalif/vitastor/blob/master/src/client/cluster_client.cpp"
click node_messenger "https://github.com/vitalif/vitastor/blob/master/src/client/messenger.cpp"
click node_osd "https://github.com/vitalif/vitastor/blob/master/src/osd/osd.cpp"
click node_blockstore "https://github.com/vitalif/vitastor/blob/master/src/blockstore/blockstore.cpp"
click node_disk "https://github.com/vitalif/vitastor/blob/master/src/blockstore/blockstore_disk.cpp"
click node_qemu "https://github.com/vitalif/vitastor/blob/master/src/client/qemu_driver.c"
click node_ublk "https://github.com/vitalif/vitastor/blob/master/src/client/ublk_server.cpp"
click node_nbd "https://github.com/vitalif/vitastor/blob/master/src/client/nbd_proxy.cpp"
click node_nfs "https://github.com/vitalif/vitastor/blob/master/src/nfs/nfs_proxy.cpp"
click node_kv "https://github.com/vitalif/vitastor/blob/master/src/kv/kv_db.cpp"
click node_csi "https://github.com/vitalif/vitastor/blob/master/csi/src/controllerserver.go"
click node_nodebinding "https://github.com/vitalif/vitastor/blob/master/node-binding/client.cc"
click node_openstack "https://github.com/vitalif/vitastor/blob/master/patches/cinder-vitastor.py"
click node_opennebula "https://github.com/vitalif/vitastor/blob/master/opennebula/remotes/datastore/vitastor/patch-oned-conf.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_cli,node_disktool toneBlue
class node_monitor,node_monhttp,node_stateclient,node_placement,node_etcd toneAmber
class node_clusterclient,node_messenger,node_osd,node_blockstore,node_disk toneMint
class node_qemu,node_ublk,node_nbd,node_nfs,node_kv toneRose
class node_csi,node_nodebinding,node_openstack,node_opennebula,node_operator,node_workload toneIndigo
```

## Components

### Administration

- [Vitastor CLI](https://github.com/vitalif/vitastor/blob/master/src/cmd/cli.cpp): `src/cmd/cli.cpp`
- [Disk management](https://github.com/vitalif/vitastor/blob/master/src/disk_tool/disk_tool.cpp): `src/disk_tool/disk_tool.cpp`

### Cluster control

- [Monitor](https://github.com/vitalif/vitastor/blob/master/mon/mon.js): `mon/mon.js`
- [Monitor HTTP](https://github.com/vitalif/vitastor/blob/master/mon/http_server.js): `mon/http_server.js`
- [State client](https://github.com/vitalif/vitastor/blob/master/src/client/etcd_state_client.cpp): `src/client/etcd_state_client.cpp`
- [PG placement](https://github.com/vitalif/vitastor/blob/master/mon/pg_gen.js): `mon/pg_gen.js`

### Storage data plane

- [Cluster client](https://github.com/vitalif/vitastor/blob/master/src/client/cluster_client.cpp): `src/client/cluster_client.cpp`
- [OSD messaging](https://github.com/vitalif/vitastor/blob/master/src/client/messenger.cpp): `src/client/messenger.cpp`
- [OSD](https://github.com/vitalif/vitastor/blob/master/src/osd/osd.cpp): `src/osd/osd.cpp`
- [Blockstore](https://github.com/vitalif/vitastor/blob/master/src/blockstore/blockstore.cpp): `src/blockstore/blockstore.cpp`
- [OSD disk](https://github.com/vitalif/vitastor/blob/master/src/blockstore/blockstore_disk.cpp): `src/blockstore/blockstore_disk.cpp`

### Workload interfaces

- [QEMU interface](https://github.com/vitalif/vitastor/blob/master/src/client/qemu_driver.c): `src/client/qemu_driver.c`
- [UBLK interface](https://github.com/vitalif/vitastor/blob/master/src/client/ublk_server.cpp): `src/client/ublk_server.cpp`
- [NBD interface](https://github.com/vitalif/vitastor/blob/master/src/client/nbd_proxy.cpp): `src/client/nbd_proxy.cpp`
- [NFS service](https://github.com/vitalif/vitastor/blob/master/src/nfs/nfs_proxy.cpp): `src/nfs/nfs_proxy.cpp`
- [Vitastor KV](https://github.com/vitalif/vitastor/blob/master/src/kv/kv_db.cpp): `src/kv/kv_db.cpp`

### Platform integrations

- [Kubernetes CSI](https://github.com/vitalif/vitastor/blob/master/csi/src/controllerserver.go): `csi/src/controllerserver.go`
- [Node binding](https://github.com/vitalif/vitastor/blob/master/node-binding/client.cc): `node-binding/client.cc`
- [OpenStack driver](https://github.com/vitalif/vitastor/blob/master/patches/cinder-vitastor.py): `patches/cinder-vitastor.py`
- [OpenNebula driver](https://github.com/vitalif/vitastor/blob/master/opennebula/remotes/datastore/vitastor/patch-oned-conf.py): `opennebula/remotes/datastore/vitastor/patch-oned-conf.py`

### Other components

- **Operator**
- **Workload**
- **etcd state**

## Connections

- Operator → Vitastor CLI: administers
- Operator → Disk management: prepares disks
- Vitastor CLI → Monitor HTTP: requests cluster operations
- Monitor → etcd state: stores cluster state
- State client → etcd state: reads cluster state
- Monitor → PG placement: generates placement
- Cluster client → State client: loads state
- Cluster client → OSD messaging: dispatches I/O
- OSD messaging → OSD: sends OSD requests
- OSD → Blockstore: executes storage operations
- Blockstore → OSD disk: reads and writes
- Workload → QEMU interface: uses
- Workload → UBLK interface: uses
- Workload → NBD interface: uses
- Workload → NFS service: mounts
- QEMU interface → Cluster client: submits I/O
- UBLK interface → Cluster client: submits I/O
- NBD interface → Cluster client: submits I/O
- NFS service → Vitastor KV: serves KV filesystem
- NFS service → Cluster client: accesses shared data
- Kubernetes CSI → Vitastor CLI: invokes volume operations
- Node binding → Cluster client: uses client API
- OpenStack driver → Vitastor CLI: integrates provisioning
- OpenNebula driver → Vitastor CLI: integrates provisioning