# leahsinger14/kubevirt architecture

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

- Interactive diagram: https://gitdiagram.com/leahsinger14/kubevirt
- Repository: https://github.com/leahsinger14/kubevirt

## Overview

KubeVirt adds VM resources and virtualization controllers/agents to Kubernetes. A user submits VM intent through the API; admission validates and mutates it, the controller reconciles it into a scheduled launcher pod, and the node handler prepares networking/devices and manages the VM through virt-launcher and libvirt. The repository also contains distinct storage, migration, snapshot/export, console/API, and monitoring capabilities. The README documents declarative VM lifecycle; component paths come from the tree, while sampled excerpts provide only partial implementation detail, so uncertain internal calls are omitted.

Main entry points: [`cmd/virt-api/virt-api.go`](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-api/virt-api.go) (virt-api), [`cmd/virt-controller/virt-controller.go`](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-controller/virt-controller.go) (virt-controller), [`pkg/virt-handler/controller.go`](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-handler/controller.go) (Node reconciliation), [`cmd/virt-handler/virt-handler.go`](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-handler/virt-handler.go) (virt-handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and admission"]
  node_virtapi["virt-api<br/>[virt-api.go]"]
  node_rest["API endpoints"]
  node_webhooks["Admission webhooks"]
end

subgraph group_control["VM control plane"]
  node_virtcontroller["virt-controller<br/>[virt-controller.go]"]
  node_vmwatch["VM reconciliation<br/>[vm.go]"]
  node_vmiwatch["VMI reconciliation<br/>[vmi.go]"]
  node_render["Launcher pod rendering<br/>[template.go]"]
  node_operator["virt-operator<br/>[virt-operator.go]"]
end

subgraph group_node["Node execution"]
  node_handler["virt-handler<br/>[virt-handler.go]"]
  node_handlercontrol["Node reconciliation<br/>[controller.go]"]
  node_launcher["virt-launcher<br/>[virt-launcher.go]"]
  node_domainmanager["Libvirt domain manager<br/>[manager.go]"]
  node_hypervisor["Hypervisor runtime<br/>[virt-runtime.go]"]
  node_network["Network setup<br/>[configurator.go]"]
end

subgraph group_data["Storage and mobility"]
  node_storage["Storage controllers<br/>[storage.go]"]
  node_backend["Backend storage<br/>[backend-storage.go]"]
  node_snapshot["Snapshots and restore<br/>[snapshot.go]"]
  node_export["VM export<br/>[export.go]"]
  node_migration["Migration synchronization"]
end

subgraph group_ops["Access and observability"]
  node_virtctl["virtctl<br/>[virtctl.go]"]
  node_metrics["Metrics and alerts<br/>[rules.go]"]
end

node_user(("VM operator"))
node_kubeapi[("Kubernetes API")]

node_user -->|"submits VM request"| node_virtapi
node_virtapi -->|"routes requests"| node_rest
node_virtapi -->|"validates admission"| node_webhooks
node_virtapi -->|"reads and writes resources"| node_kubeapi
node_virtcontroller -->|"watches resources"| node_kubeapi
node_virtcontroller -->|"reconciles VMs"| node_vmwatch
node_virtcontroller -->|"reconciles VMIs"| node_vmiwatch
node_vmwatch -->|"renders launcher pod"| node_render
node_render -->|"creates pod resources"| node_kubeapi
node_virtcontroller -->|"reconciles volume status"| node_storage
node_storage -->|"creates backend PVCs"| node_backend
node_handler -->|"runs node control"| node_handlercontrol
node_handlercontrol -->|"reads and patches VMI"| node_kubeapi
node_handlercontrol -->|"sets up networking"| node_network
node_handlercontrol -->|"manages launcher"| node_launcher
node_launcher -->|"manages domains"| node_domainmanager
node_domainmanager -->|"controls VM runtime"| node_hypervisor
node_migration -->|"synchronizes migration state"| node_kubeapi
node_user -->|"runs VM commands"| node_virtctl
node_virtctl -->|"calls API"| node_virtapi
node_virtapi -.->|"snapshot API"| node_snapshot
node_virtapi -.->|"export API"| node_export
node_handler -.->|"provides runtime metrics"| node_metrics
node_operator -->|"manages cluster resources"| node_kubeapi

click node_virtapi "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-api/virt-api.go"
click node_rest "https://github.com/leahsinger14/kubevirt/tree/main/pkg/virt-api/rest"
click node_webhooks "https://github.com/leahsinger14/kubevirt/tree/main/pkg/virt-api/webhooks"
click node_virtcontroller "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-controller/virt-controller.go"
click node_vmwatch "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vm/vm.go"
click node_vmiwatch "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vmi/vmi.go"
click node_render "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/services/template.go"
click node_operator "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-operator/virt-operator.go"
click node_handler "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-handler/virt-handler.go"
click node_handlercontrol "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-handler/controller.go"
click node_launcher "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-launcher/virt-launcher.go"
click node_domainmanager "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-launcher/virtwrap/manager.go"
click node_hypervisor "https://github.com/leahsinger14/kubevirt/blob/main/pkg/hypervisor/virt-runtime.go"
click node_network "https://github.com/leahsinger14/kubevirt/blob/main/pkg/network/setup/launcher/configurator.go"
click node_storage "https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vmi/storage.go"
click node_backend "https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/backend-storage/backend-storage.go"
click node_snapshot "https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/snapshot/snapshot.go"
click node_export "https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/export/export/export.go"
click node_migration "https://github.com/leahsinger14/kubevirt/blob/main/pkg/synchronization-controller/synchronization-controller.go"
click node_virtctl "https://github.com/leahsinger14/kubevirt/blob/main/cmd/virtctl/virtctl.go"
click node_metrics "https://github.com/leahsinger14/kubevirt/blob/main/pkg/monitoring/rules/rules.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_virtapi,node_rest,node_webhooks toneBlue
class node_virtcontroller,node_vmwatch,node_vmiwatch,node_render,node_operator,node_kubeapi toneAmber
class node_handler,node_handlercontrol,node_launcher,node_domainmanager,node_hypervisor,node_network toneMint
class node_storage,node_backend,node_snapshot,node_export,node_migration toneRose
class node_virtctl,node_metrics,node_user toneIndigo
```

## Components

### API and admission

- [virt-api](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-api/virt-api.go): `cmd/virt-api/virt-api.go`
- [API endpoints](https://github.com/leahsinger14/kubevirt/tree/main/pkg/virt-api/rest): `pkg/virt-api/rest`
- [Admission webhooks](https://github.com/leahsinger14/kubevirt/tree/main/pkg/virt-api/webhooks): `pkg/virt-api/webhooks`

### VM control plane

- [virt-controller](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-controller/virt-controller.go): `cmd/virt-controller/virt-controller.go`
- [VM reconciliation](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vm/vm.go): `pkg/virt-controller/watch/vm/vm.go`
- [VMI reconciliation](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vmi/vmi.go): `pkg/virt-controller/watch/vmi/vmi.go`
- [Launcher pod rendering](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/services/template.go): `pkg/virt-controller/services/template.go`
- [virt-operator](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-operator/virt-operator.go): `cmd/virt-operator/virt-operator.go`

### Node execution

- [virt-handler](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-handler/virt-handler.go): `cmd/virt-handler/virt-handler.go`
- [Node reconciliation](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-handler/controller.go): `pkg/virt-handler/controller.go`
- [virt-launcher](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virt-launcher/virt-launcher.go): `cmd/virt-launcher/virt-launcher.go`
- [Libvirt domain manager](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-launcher/virtwrap/manager.go): `pkg/virt-launcher/virtwrap/manager.go`
- [Hypervisor runtime](https://github.com/leahsinger14/kubevirt/blob/main/pkg/hypervisor/virt-runtime.go): `pkg/hypervisor/virt-runtime.go`
- [Network setup](https://github.com/leahsinger14/kubevirt/blob/main/pkg/network/setup/launcher/configurator.go): `pkg/network/setup/launcher/configurator.go`

### Storage and mobility

- [Storage controllers](https://github.com/leahsinger14/kubevirt/blob/main/pkg/virt-controller/watch/vmi/storage.go): `pkg/virt-controller/watch/vmi/storage.go`
- [Backend storage](https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/backend-storage/backend-storage.go): `pkg/storage/backend-storage/backend-storage.go`
- [Snapshots and restore](https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/snapshot/snapshot.go): `pkg/storage/snapshot/snapshot.go`
- [VM export](https://github.com/leahsinger14/kubevirt/blob/main/pkg/storage/export/export/export.go): `pkg/storage/export/export/export.go`
- [Migration synchronization](https://github.com/leahsinger14/kubevirt/blob/main/pkg/synchronization-controller/synchronization-controller.go): `pkg/synchronization-controller/synchronization-controller.go`

### Access and observability

- [virtctl](https://github.com/leahsinger14/kubevirt/blob/main/cmd/virtctl/virtctl.go): `cmd/virtctl/virtctl.go`
- [Metrics and alerts](https://github.com/leahsinger14/kubevirt/blob/main/pkg/monitoring/rules/rules.go): `pkg/monitoring/rules/rules.go`

### Other components

- **VM operator**
- **Kubernetes API**

## Connections

- VM operator → virt-api: submits VM request
- virt-api → API endpoints: routes requests
- virt-api → Admission webhooks: validates admission
- virt-api → Kubernetes API: reads and writes resources
- virt-controller → Kubernetes API: watches resources
- virt-controller → VM reconciliation: reconciles VMs
- virt-controller → VMI reconciliation: reconciles VMIs
- VM reconciliation → Launcher pod rendering: renders launcher pod
- Launcher pod rendering → Kubernetes API: creates pod resources
- virt-controller → Storage controllers: reconciles volume status
- Storage controllers → Backend storage: creates backend PVCs
- virt-handler → Node reconciliation: runs node control
- Node reconciliation → Kubernetes API: reads and patches VMI
- Node reconciliation → Network setup: sets up networking
- Node reconciliation → virt-launcher: manages launcher
- virt-launcher → Libvirt domain manager: manages domains
- Libvirt domain manager → Hypervisor runtime: controls VM runtime
- Migration synchronization → Kubernetes API: synchronizes migration state
- VM operator → virtctl: runs VM commands
- virtctl → virt-api: calls API
- virt-api → Snapshots and restore: snapshot API
- virt-api → VM export: export API
- virt-handler → Metrics and alerts: provides runtime metrics
- virt-operator → Kubernetes API: manages cluster resources