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 │
                          └───────────┬────────────┘
                                      │ watch / status
                          ┌───────────▼────────────┐
                          │   virtrigaud-manager   │
                          │  (8 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 below), 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.6 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.
VMPlacementPolicy Placement / anti-affinity rules.
VMClone One-shot clone of an existing VM.

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.6.

Recent Releases

  • v0.3.6 — Observability + supply-chain release.
    • G6 CircuitBreaker now wired on the provider gRPC RPC path. One breaker per Provider CR, default thresholds FailureThreshold=10, ResetTimeout=60s, HalfOpenMaxCalls=3. Infrastructure-class gRPC errors (Unavailable, DeadlineExceeded, Internal, Unknown) count toward the threshold; business errors (NotFound, InvalidArgument, …) pass through unchanged. See Resilience.
    • G7 metric family rollout completed. New families: virtrigaud_vm_operations_total (G7.1), virtrigaud_ip_discovery_duration_seconds (G7.2), virtrigaud_provider_tasks_inflight (G7.3). virtrigaud_queue_depth deprecated in favour of controller-runtime's workqueue_depth{name} (G7.4) — removal scheduled for v0.4.0 or later.
    • H1 build-path consolidation. One manager entrypoint, one manager Dockerfile. build/Dockerfile.manager now parametrised with BUILDER_IMAGE / BASE_IMAGE / GOPROXY / CA-cert handling for corporate / banking deployments. Closes latent bug #113.
    • Go toolchain floor: 1.24.0 → 1.26.0. Source builders need Go 1.26+ installed locally; binary consumers via released images unaffected.
    • Security: go.opentelemetry.io/otel v1.39.0 → v1.43.0 (closes 3 HIGH-severity CVEs, two of which are PATH-hijacking primitives).
  • 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