Skip to content

VirtRigaud Documentation

Welcome to the VirtRigaud documentation. VirtRigaud is a Kubernetes operator for managing virtual machines across multiple hypervisors — VMware vSphere, Libvirt/KVM, and Proxmox VE — through a single declarative API.

What VirtRigaud is

VirtRigaud lets you declare VMs the same way you declare Deployments. A VirtualMachine custom resource describes the desired VM (size, image, networks, disks, power state); a small set of controllers in the manager reconcile that desire against whichever hypervisor backs the namespace's Provider.

Hypervisor-specific logic does not run inside the manager. Each provider runs as its own gRPC server pod, and the manager talks to it over a stable proto contract (proto/provider/v1/provider.proto). This isolates hypervisor failures, lets providers be upgraded independently, and means a misbehaving provider cannot crash the rest of the operator.

Architecture at a glance

                          ┌────────────────────────┐
                          │   Kubernetes API       │
                          │  VirtualMachine,       │
                          │  Provider, VMClass,    │
                          │  VMImage, VMNetwork-   │
                          │  Attachment, VM-       │
                          │  Snapshot, VMMigration,│
                          │  VMClone, VMSet,       │
                          │  VMPlacementPolicy     │
                          └───────────┬────────────┘
                                      │ watch / status
                          ┌───────────▼────────────┐
                          │   virtrigaud-manager   │
                          │  (9 reconcilers)       │
                          │                        │
                          │  per-RPC interceptors: │
                          │   1. metrics (G4)      │
                          │   2. CircuitBreaker(G6)│
                          └───────────┬────────────┘
                                      │ gRPC (mTLS optional)
        ┌─────────────────────────────┼─────────────────────────────┐
        │                             │                             │
┌───────▼──────┐             ┌────────▼─────────┐          ┌────────▼────────┐
│ provider-    │             │ provider-        │          │ provider-       │
│ vsphere      │             │ libvirt          │          │ proxmox         │
│ (govmomi)    │             │ (virsh + libssh) │          │ (REST API)      │
└──────────────┘             └──────────────────┘          └─────────────────┘
        │                             │                             │
   vCenter / ESXi              KVM / QEMU host                Proxmox VE host

One manager binary, one manager Dockerfile (consolidated in v0.3.6 — see H1 in that release), and one gRPC client per Provider CR. Each outbound RPC passes through two unary interceptors: a metrics interceptor (per-RPC latency and status-code counter, G4) and a CircuitBreaker interceptor (one breaker per Provider CR, G6).

Quick Navigation

Getting Started

Guides

Provider-Specific Guides

Advanced Topics

Operations

Security Configuration

References

Development

Examples Directory

Custom Resources

VirtRigaud v0.3.9 ships 10 Custom Resource Definitions in the infra.virtrigaud.io/v1beta1 API group:

Kind Purpose
VirtualMachine Desired state of a single VM (image, class, networks, disks, power state).
Provider Connection details for a hypervisor (vSphere / Libvirt / Proxmox / Mock) and its provider-server Deployment.
VMClass Reusable sizing template (CPU, memory, firmware).
VMImage Reference to a hypervisor template / OVA / cloud image.
VMNetworkAttachment Logical network the VM attaches to (resolved per-provider).
VMSnapshot A point-in-time snapshot of a VirtualMachine.
VMMigration Inter-provider VM migration (export → import).
VMSet Replica-set of identical VMs. CRD available; controller stub only — Ready=False/ControllerNotImplemented in v0.3.9.
VMPlacementPolicy Placement / anti-affinity rules. Applied via VirtualMachine.spec.placementRef; no standalone controller.
VMClone One-shot full or linked clone of an existing VM (vSphere, Proxmox, and Libvirt as of v0.3.9).

The manager also runs a VMAdoption reconciler (not a CRD — it reconciles Provider resources annotated with virtrigaud.io/adopt-vms: "true", discovers VMs the hypervisor already owns, and creates VirtualMachine CRs labelled virtrigaud.io/adopted=true for them, plus an adopted-Ncpu-Nmb VMClass per unique sizing). See the generated CRD reference for the full schema.

Version Information

This documentation covers VirtRigaud v0.3.11.

Recent Releases

  • v0.3.11 — NFS cross-hypervisor migration staging backend (ADR-0006 Slice 4).
    • Second storage-agnostic VMMigration backend: NFS (#236). Alongside the S3 backend, the disk can now be staged on an NFS export and moved with qemu-img's native transport — no PVC, no relay, no S3 credentials. Lab-validated across all three providers (vSphere, libvirt, Proxmox VE) in both directions against a real OpenMediaVault server.
    • Per-provider NFS transport. libvirt (host-side) and vSphere (pod-side) use qemu-img's nfs:// libnfs driver; Proxmox kernel-mounts the export because pve-qemu-kvm ships no libnfs driver.
    • nfs.uid / nfs.gid are effectively mandatory for cross-provider migrations (AUTH_SYS authorizes by the numeric uid/gid each leg presents); set them to the export owner. The staged object is a single flat file in the export root.
    • Proxmox now advertises s3 and nfs (not PVC: its disks live on the node, unreachable by a pod-mounted PVC). The full 3-hypervisor matrix is now validated in both directions over both staging backends. See the VM Migration User Guide.
  • v0.3.9 — Libvirt online operations + clone + image-prepare + memory snapshots on all three providers.
    • Libvirt online CPU/memory reconfigure (#203). virsh setvcpus/setmem --live with no power-cycle for VMs created with cpuHotAddEnabled/memoryHotAddEnabled on the VMClass (4× headroom, 64-vCPU cap). Lab-proven.
    • Libvirt online disk expansion (#201). virsh blockresize + best-effort in-guest FS grow. Grow-only; no power-cycle. Lab-proven.
    • Libvirt memory snapshots (#202). RAM-inclusive checkpoints on running VMs. Stopped VM downgrades to disk-only with a WARN.
    • Libvirt clone (#153) + clone hardening (#208/#221). Full and linked (qcow2 overlay) clones, same-provider. UEFI nvram re-pointed per clone; hot-add headroom preserved across class-override clones.
    • End-to-end image preparation (#154). VMImage.spec.prepare drives lazy VM-create-time image import on libvirt, vSphere (OVA/OVF), and Proxmox. prepare.onMissing: Fail holds VM creation with WaitingForDependencies until the image is ready.
    • Proxmox export compression (#219). ExportDisk honors Compress for qcow2 targets.
    • Memory snapshots on all three providers. vSphere (#200): CreateSnapshot(memory=true); libvirt (#202): snapshot-create-as; Proxmox: PVE-native.
  • v0.3.8 — VMClone MVP + VMSet stub + secure-by-default chart.
    • VMClone controller (MVP). Full and linked clones functional via VMClone CRD (vSphere and Proxmox; libvirt added in v0.3.9).
    • VMSet: CRD defined, controller not yet active. A VMSet resource is accepted but emits Ready=False / Reason=ControllerNotImplemented.
    • Chart (#173): providers disabled by default. Opt-in via providers.<type>.enabled=true.
  • v0.3.7 — mTLS enforcement, multi-arch images, circuit-breaker metrics.
  • v0.3.6 — Observability + supply-chain release (CircuitBreaker, G7 metrics, H1 build consolidation, Go 1.26 floor, OTel CVE fixes).
  • v0.3.5 — Observability G-track foundation (RPC metrics, error counters, reconcile metrics).
  • v0.3.3 — Changelog organisation with versioned release headers.
  • v0.2.3 — Provider feature parity: Reconfigure, Clone, TaskStatus, ConsoleURL.

See CHANGELOG.md for the complete version history.

Provider Status

Provider Status Maturity Documentation
vSphere Production Ready Stable Guide
Libvirt/KVM Production Ready Stable Guide
Proxmox VE Production Ready Beta Guide
Mock Complete Testing providers/tutorial.md

Support