# kubevirt/kubevirt architecture

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

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

## Overview

KubeVirt extends Kubernetes with VM custom resources and cluster controllers and agents that reconcile them into running virtual machines. The documented user flow is declarative VM creation, scheduling, launch, stop, and deletion. The graph includes API admission, controller reconciliation, node handling, the launcher, and notable storage, migration, and device-management capabilities. Relationships are limited to README statements and source-index references or excerpts; several unsampled subsystems are represented by their exact tree paths, with uncertain wiring omitted.

Main entry points: [`pkg/virt-controller/watch/application.go`](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-controller/watch/application.go) (VM controller), [`pkg/virt-handler/controller.go`](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-handler/controller.go) (Node handler), [`pkg/virt-launcher/virtwrap/manager.go`](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-launcher/virtwrap/manager.go) (VM launcher), [`pkg/virt-api/api.go`](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-api/api.go) (VM resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and configuration"]
  node_vmresources["VM resources<br/>[api.go]"]
  node_admission["Admission webhooks"]
end

subgraph group_control["Cluster control"]
  node_operator["Cluster operator<br/>[application.go]"]
  node_virtcontroller["VM controller<br/>[application.go]"]
  node_instancetype["Instance types<br/>[controller.go]"]
  node_storagecontroller["Storage reconciliation<br/>[storage.go]"]
end

subgraph group_runtime["Node runtime"]
  node_handler["Node handler<br/>[controller.go]"]
  node_devicemanager["Device manager"]
  node_launcher["VM launcher<br/>[manager.go]"]
  node_hooks["Hook manager<br/>[manager.go]"]
end

subgraph group_features["VM capabilities"]
  node_backendstorage["Storage backend<br/>[backend-storage.go]"]
  node_hotplugadmission["Hotplug validation<br/>[storagehotplug.go]"]
  node_migration["Migration synchronization"]
  node_migrationapp["Migration service"]
  node_network["Network configuration<br/>[configurator.go]"]
end

subgraph group_operations["Operations"]
  node_metrics["Monitoring metrics<br/>[collector.go]"]
  node_certificates["Certificate management<br/>[cert-manager.go]"]
end

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

node_user -->|"declares VM"| node_kubeapi
node_kubeapi -->|"manages resources"| node_vmresources
node_vmresources -.-> node_admission
node_operator -->|"uses certificates"| node_certificates
node_virtcontroller -->|"configures hooks"| node_hooks
node_virtcontroller -->|"registers storage watch"| node_storagecontroller
node_storagecontroller -->|"calls storage backend"| node_backendstorage
node_instancetype -.-> node_virtcontroller
node_handler -->|"uses launcher client"| node_launcher
node_devicemanager -.-> node_handler
node_launcher -->|"uses hook manager"| node_hooks
node_launcher -->|"uses network manager"| node_network
node_migrationapp -->|"runs controller"| node_migration
node_migration -->|"uses storage backend"| node_backendstorage
node_handler -.-> node_metrics
node_virtcontroller -->|"schedules VMs"| node_kubeapi
node_virtcontroller -.->|"coordinates launch"| node_handler
node_handler -.->|"launches VM"| node_launcher
node_hotplugadmission -.-> node_admission

click node_vmresources "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-api/api.go"
click node_admission "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-api/webhooks/validating-webhook/validating-webhook.go"
click node_operator "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-operator/application.go"
click node_virtcontroller "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-controller/watch/application.go"
click node_instancetype "https://github.com/kubevirt/kubevirt/blob/main/pkg/instancetype/controller/vm/controller.go"
click node_storagecontroller "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-controller/watch/vmi/storage.go"
click node_backendstorage "https://github.com/kubevirt/kubevirt/blob/main/pkg/storage/backend-storage/backend-storage.go"
click node_hotplugadmission "https://github.com/kubevirt/kubevirt/blob/main/pkg/storage/admitters/storagehotplug.go"
click node_handler "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-handler/controller.go"
click node_devicemanager "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-handler/device-manager/device_controller.go"
click node_launcher "https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-launcher/virtwrap/manager.go"
click node_hooks "https://github.com/kubevirt/kubevirt/blob/main/pkg/hooks/manager.go"
click node_migration "https://github.com/kubevirt/kubevirt/blob/main/pkg/synchronization-controller/synchronization-controller.go"
click node_migrationapp "https://github.com/kubevirt/kubevirt/blob/main/cmd/synchronization-controller/synchronization-controller.go"
click node_network "https://github.com/kubevirt/kubevirt/blob/main/pkg/network/setup/launcher/configurator.go"
click node_metrics "https://github.com/kubevirt/kubevirt/blob/main/pkg/monitoring/metrics/virt-handler/domainstats/collector.go"
click node_certificates "https://github.com/kubevirt/kubevirt/blob/main/pkg/certificates/bootstrap/cert-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_vmresources,node_admission,node_user toneBlue
class node_operator,node_virtcontroller,node_instancetype,node_storagecontroller toneAmber
class node_handler,node_devicemanager,node_launcher,node_hooks,node_kubeapi toneMint
class node_backendstorage,node_hotplugadmission,node_migration,node_migrationapp,node_network toneRose
class node_metrics,node_certificates toneIndigo
```

## Components

### API and configuration

- [VM resources](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-api/api.go): `pkg/virt-api/api.go`
- [Admission webhooks](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-api/webhooks/validating-webhook/validating-webhook.go): `pkg/virt-api/webhooks/validating-webhook/validating-webhook.go`

### Cluster control

- [Cluster operator](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-operator/application.go): `pkg/virt-operator/application.go`
- [VM controller](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-controller/watch/application.go): `pkg/virt-controller/watch/application.go`
- [Instance types](https://github.com/kubevirt/kubevirt/blob/main/pkg/instancetype/controller/vm/controller.go): `pkg/instancetype/controller/vm/controller.go`
- [Storage reconciliation](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-controller/watch/vmi/storage.go): `pkg/virt-controller/watch/vmi/storage.go`

### Node runtime

- [Node handler](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-handler/controller.go): `pkg/virt-handler/controller.go`
- [Device manager](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-handler/device-manager/device_controller.go): `pkg/virt-handler/device-manager/device_controller.go`
- [VM launcher](https://github.com/kubevirt/kubevirt/blob/main/pkg/virt-launcher/virtwrap/manager.go): `pkg/virt-launcher/virtwrap/manager.go`
- [Hook manager](https://github.com/kubevirt/kubevirt/blob/main/pkg/hooks/manager.go): `pkg/hooks/manager.go`

### VM capabilities

- [Storage backend](https://github.com/kubevirt/kubevirt/blob/main/pkg/storage/backend-storage/backend-storage.go): `pkg/storage/backend-storage/backend-storage.go`
- [Hotplug validation](https://github.com/kubevirt/kubevirt/blob/main/pkg/storage/admitters/storagehotplug.go): `pkg/storage/admitters/storagehotplug.go`
- [Migration synchronization](https://github.com/kubevirt/kubevirt/blob/main/pkg/synchronization-controller/synchronization-controller.go): `pkg/synchronization-controller/synchronization-controller.go`
- [Migration service](https://github.com/kubevirt/kubevirt/blob/main/cmd/synchronization-controller/synchronization-controller.go): `cmd/synchronization-controller/synchronization-controller.go`
- [Network configuration](https://github.com/kubevirt/kubevirt/blob/main/pkg/network/setup/launcher/configurator.go): `pkg/network/setup/launcher/configurator.go`

### Operations

- [Monitoring metrics](https://github.com/kubevirt/kubevirt/blob/main/pkg/monitoring/metrics/virt-handler/domainstats/collector.go): `pkg/monitoring/metrics/virt-handler/domainstats/collector.go`
- [Certificate management](https://github.com/kubevirt/kubevirt/blob/main/pkg/certificates/bootstrap/cert-manager.go): `pkg/certificates/bootstrap/cert-manager.go`

### Other components

- **VM user**
- **Kubernetes API**

## Connections

- VM user → Kubernetes API: declares VM
- Kubernetes API → VM resources: manages resources
- VM resources → Admission webhooks
- Cluster operator → Certificate management: uses certificates (evidence: `pkg/virt-operator/application.go`)
- VM controller → Hook manager: configures hooks (evidence: `pkg/virt-controller/watch/application.go`)
- VM controller → Storage reconciliation: registers storage watch (evidence: `pkg/virt-controller/watch/application.go`)
- Storage reconciliation → Storage backend: calls storage backend (evidence: `pkg/virt-controller/watch/vmi/storage.go`)
- Instance types → VM controller
- Node handler → VM launcher: uses launcher client (evidence: `pkg/virt-handler/controller.go`)
- Device manager → Node handler
- VM launcher → Hook manager: uses hook manager (evidence: `pkg/virt-launcher/virtwrap/manager.go`)
- VM launcher → Network configuration: uses network manager (evidence: `pkg/virt-launcher/virtwrap/manager.go`)
- Migration service → Migration synchronization: runs controller (evidence: `cmd/synchronization-controller/synchronization-controller.go`)
- Migration synchronization → Storage backend: uses storage backend (evidence: `pkg/storage/backend-storage/backend-storage.go`)
- Node handler → Monitoring metrics
- VM controller → Kubernetes API: schedules VMs
- VM controller → Node handler: coordinates launch
- Node handler → VM launcher: launches VM
- Hotplug validation → Admission webhooks
