Custom Resource Definitions (CRDs)¶

This document describes all Custom Resource Definitions provided by VirtRigaud.

API group: infra.virtrigaud.io / Version: v1beta1

VirtRigaud ships 10 CRDs at v0.3.8. For the full auto-generated field reference, see generated-crd-docs.md.

Controller status at v0.3.8:

VMAdoption is a controller (in internal/controller/), not a CRD.

VirtualMachine¶

The VirtualMachine CRD represents a virtual machine instance managed by a provider.

Full schema: generated-crd-docs.md#virtualmachine

Spec¶

* imageRef and importedDisk are mutually exclusive. One is typically required to create a VM.

Status¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VirtualMachine
metadata:
  name: web-server
spec:
  providerRef:
    name: vsphere-prod
  classRef:
    name: small
  imageRef:
    name: ubuntu-22-template
  powerState: On
  placement:
    cluster: Compute-Cluster
    resourcePool: Production
    folder: /vm/web
    storagePod: DatastoreCluster-SSD   # auto-selects datastore with most free space
  networks:
    - name: app-net
      networkRef:
        name: app-network-attachment
  disks:
    - name: data
      sizeGiB: 100
      type: thin
  lifecycle:
    gracefulShutdownTimeout: "120s"
    preStop:
      snapshot:
        name: "pre-shutdown"
        includeMemory: false

VMClass¶

The VMClass CRD defines resource allocation and hardware profile for virtual machines.

Full schema: generated-crd-docs.md#vmclass

Spec¶

DiskDefaults¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMClass
metadata:
  name: small
spec:
  cpu: 2
  memory: "4Gi"
  firmware: UEFI
  diskDefaults:
    type: thin
    size: "40Gi"
  guestToolsPolicy: install

VMImage¶

The VMImage CRD defines base templates or images for virtual machines.

Full schema: generated-crd-docs.md#vmimage

Spec¶

ImageSource sub-fields (provider-specific):

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMImage
metadata:
  name: ubuntu-22-template
spec:
  source:
    vsphere:
      templateName: "tmpl-ubuntu-22.04-cloudimg"
    libvirt:
      url: "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
      format: qcow2

VMNetworkAttachment¶

The VMNetworkAttachment CRD defines provider-specific network configurations that VMs reference.

Full schema: generated-crd-docs.md#vmnetworkattachment

Spec¶

Provider-specific network sub-fields:

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMNetworkAttachment
metadata:
  name: app-network
spec:
  network:
    vsphere:
      portgroup: "PG-App-VLAN100"
    proxmox:
      bridge: vmbr0
      vlanTag: 100
  ipAllocation:
    type: DHCP

VMs reference network attachments via spec.networks[].networkRef:

spec:
  networks:
    - name: app-net
      networkRef:
        name: app-network

Provider¶

The Provider CRD configures hypervisor connection details and the provider runtime.

Full schema: generated-crd-docs.md#provider

Spec¶

ProviderDefaults¶

Status¶

ReportedCapabilities (v0.3.8)¶

The manager calls the provider's GetCapabilities RPC after each successful connect and writes the result into status.reportedCapabilities. A CapabilitiesReported condition is also set (True on success, False with reason Unavailable if the RPC fails or the provider is unreachable).

Full schema: generated-crd-docs.md#provider

ProviderRuntimeSpec¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: Provider
metadata:
  name: vsphere-prod
spec:
  type: vsphere
  endpoint: https://vcenter.example.com/sdk
  credentialSecretRef:
    name: vsphere-creds
  defaults:
    cluster: Compute-Cluster
    storagePod: DatastoreCluster-SSD   # auto-selects datastore with most free space
  runtime:
    image: "ghcr.io/projectbeskar/virtrigaud/provider-vsphere:v0.3.8"
    service:
      port: 9443

Common Types¶

ObjectRef¶

Placement¶

Inline placement hints on a VirtualMachine. All fields are optional.

DiskSpec¶

VMNetworkRef¶

References a VMNetworkAttachment from a VirtualMachine.

VirtualMachineLifecycle¶

LifecycleHandler (action types — pick one)¶

UserData¶

ImportedDiskRef¶

Used for adopted or migrated VMs instead of imageRef.

VMMigration¶

The VMMigration CRD manages live or offline migration of a virtual machine from one provider to another. Only the vSphere → Libvirt direction is tested. Other pairs may work but are unverified.

Full schema: generated-crd-docs.md#vmmigration

Spec summary¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMMigration
metadata:
  name: web-server-migration
spec:
  sourceVMRef:
    name: web-server
  targetProviderRef:
    name: libvirt-dev
  cutoverPolicy: Immediate

VMSnapshot¶

The VMSnapshot CRD represents a point-in-time snapshot of a VirtualMachine. Creating a VMSnapshot resource triggers the provider's snapshot RPC. The libvirt ImagePrepare RPC remains a stub (#154).

Full schema: generated-crd-docs.md#vmsnapshot

Spec summary¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMSnapshot
metadata:
  name: web-server-snap-pre-upgrade
spec:
  vmRef:
    name: web-server
  includeMemory: false
  description: "Before OS upgrade"

VMSet¶

The VMSet CRD is intended to manage a fleet of identically-configured VirtualMachines (analogous to a ReplicaSet for VMs). The controller has not yet been implemented.

Full schema: generated-crd-docs.md#vmset

Spec summary¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMSet
metadata:
  name: web-workers
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web-worker
  template:
    metadata:
      labels:
        app: web-worker
    spec:
      providerRef:
        name: vsphere-prod
      classRef:
        name: small
      imageRef:
        name: ubuntu-22-template
      powerState: On

VMPlacementPolicy¶

The VMPlacementPolicy CRD defines affinity and anti-affinity rules that influence where VMs are placed within a provider. VirtualMachines reference a policy via spec.placementRef.

Full schema: generated-crd-docs.md#vmplacementpolicy

Spec summary¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMPlacementPolicy
metadata:
  name: spread-web-workers
spec:
  antiAffinity:
    hostAntiAffinity:
      matchLabels:
        app: web-worker

VMClone¶

The VMClone CRD manages a clone operation — creates a new VirtualMachine from a source VM. As of v0.3.8 the VMClone controller is active (MVP). See limitations below.

Full schema: generated-crd-docs.md#vmclone

v0.3.8 limitations¶

• Source: only source.vmRef (clone from a live VM) is supported. Using source.snapshotRef, source.templateRef, or source.imageRef will set the VMClone to Failed with message "clone source type not yet supported; use source.vmRef".
• Same-provider only: the target must resolve to the same provider as the source VM. Cross-provider clone is not supported.
• Linked clones: supported only when the provider advertises supportsLinkedClones=true in its status.reportedCapabilities. vSphere and Proxmox support this; the libvirt Clone RPC is Unimplemented (#153) — any VMClone targeting a libvirt provider will fail.
• Produced VM: the controller creates a target VirtualMachine CR labeled virtrigaud.io/adopted=true with Status.ID seeded to the cloned VM's provider ID. The target VM is bound to the VMClone via owner references.
• Deletion: deleting a VMClone does not delete the produced VirtualMachine. The target VM must be deleted separately.

Spec summary¶

Status¶

Example¶

apiVersion: infra.virtrigaud.io/v1beta1
kind: VMClone
metadata:
  name: web-server-clone
spec:
  source:
    vmRef:
      name: web-server
  target:
    name: web-server-staging
    classRef:
      name: small
  options:
    type: FullClone
    powerOn: false

CRD count at v0.3.8¶

The 10 CRDs in infra.virtrigaud.io/v1beta1: VirtualMachine, Provider, VMClass, VMImage, VMNetworkAttachment, VMMigration, VMSnapshot, VMSet, VMPlacementPolicy, VMClone.

VMAdoption is a controller (in internal/controller/), not a CRD. There is no VMAdoption resource in the API group.

For the full machine-generated field reference, see generated-crd-docs.md.