Helm-only Installation¶

This guide covers installing VirtRigaud v0.3.8 using only Helm (CRDs included in the chart) and verifying the installation is healthy.

Prerequisites¶

Kubernetes cluster (1.26+)
Helm 3.8+
kubectl configured to access your cluster

Installation¶

Add the Helm repository¶

helm repo add virtrigaud https://projectbeskar.github.io/virtrigaud
helm repo update virtrigaud

Install VirtRigaud v0.3.8¶

helm install virtrigaud virtrigaud/virtrigaud \
  --version 0.3.11 \
  --namespace virtrigaud-system \
  --create-namespace \
  --wait \
  --timeout 10m

Providers are disabled by default in v0.3.8

The chart now deploys only the manager by default. Templated provider Deployments are opt-in. Set providers.<type>.enabled=true to deploy a provider alongside the manager, or manage provider pods independently as Provider CRs. Example:

helm install virtrigaud virtrigaud/virtrigaud \
  --version 0.3.11 \
  --namespace virtrigaud-system \
  --create-namespace \
  --set providers.vsphere.enabled=true

mTLS required

Every Provider CR must have a spec.runtime.service.tls block. For chart-templated providers, the providerTLS Helm values block supplies TLS configuration without editing each Provider CR directly:

# values.yaml excerpt
providerTLS:
  secretName: "my-provider-tls-secret"   # Secret with tls.crt, tls.key, ca.crt
  allowedSANs:
    - "manager.virtrigaud-system.svc"
  insecure: false                         # set true only when secretName is empty (lab only)

Operators managing Provider CRs directly must add the tls block themselves. See the upgrade guide for the full remediation steps.

--wait blocks until all pods are ready. --timeout 10m matches the default provider image pull time on slow registries.

Skip CRDs (if already installed separately)¶

helm install virtrigaud virtrigaud/virtrigaud \
  --version 0.3.11 \
  --namespace virtrigaud-system \
  --create-namespace \
  --skip-crds \
  --wait

Verify Installation¶

Check pods and Helm release¶

# Manager pod is running
kubectl get pods -n virtrigaud-system

# Helm release is at v0.3.8
helm list -n virtrigaud-system
# NAME         NAMESPACE          REVISION  CHART                APP VERSION
# virtrigaud   virtrigaud-system  1         virtrigaud-0.3.8     v0.3.8

Expected output from helm list:

CHART column: virtrigaud-0.3.8
APP VERSION column: v0.3.8

Verify the manager image tag¶

kubectl get deployment virtrigaud-manager -n virtrigaud-system \
  -o jsonpath='{.spec.template.spec.containers[0].image}'
# ghcr.io/projectbeskar/virtrigaud/manager:v0.3.8

Confirm v0.3.8 metrics are available¶

kubectl port-forward -n virtrigaud-system svc/virtrigaud-manager 8080:8080 &
curl -s http://localhost:8080/metrics | grep '^virtrigaud_build_info'

Expected:

virtrigaud_build_info{component="manager",git_sha="<sha>",go_version="go1.26.x",version="v0.3.8"} 1

Metric families (seeded to 0 at boot before any Provider CRs are created):

curl -s http://localhost:8080/metrics | grep 'virtrigaud_circuit_breaker\|virtrigaud_provider_tasks_inflight'

Once at least one Provider CR exists you will see:

virtrigaud_circuit_breaker_state{provider="<name>",provider_type="<type>"} 0
virtrigaud_provider_tasks_inflight{provider="<name>",provider_type="<type>"} 0

Reconcile metrics now include kind="VMClone" and kind="VMSet" series (seeded to 0 at boot). For the full metrics surface see the Observability Guide.

Check all 10 CRDs are installed¶

kubectl get crds | grep virtrigaud.io

Expected CRDs (10 total):

virtualmachines.infra.virtrigaud.io
providers.infra.virtrigaud.io
vmclasses.infra.virtrigaud.io
vmimages.infra.virtrigaud.io
vmnetworkattachments.infra.virtrigaud.io
vmmigrations.infra.virtrigaud.io
vmsnapshots.infra.virtrigaud.io
vmsets.infra.virtrigaud.io
vmplacementpolicies.infra.virtrigaud.io
vmclones.infra.virtrigaud.io

Verify API Version¶

Confirm v1beta1 is the storage version:

kubectl get crd virtualmachines.infra.virtrigaud.io \
  -o jsonpath='{.spec.versions[?(@.storage==true)].name}'
# v1beta1

Troubleshooting¶

Manager pod not starting¶

kubectl describe pod -n virtrigaud-system -l app.kubernetes.io/name=virtrigaud
kubectl logs -n virtrigaud-system deployment/virtrigaud-manager

Common causes: image pull failure, missing RBAC, CRD version mismatch.

`virtrigaud_build_info` returns nothing¶

The manager process has not started or the metrics port is not reachable. Check:

kubectl get svc -n virtrigaud-system | grep manager

Circuit breaker open on startup¶

If a Provider CR already existed before this install, you may see:

virtrigaud_circuit_breaker_state{provider="my-provider",provider_type="libvirt"} 2

A circuit breaker that opens on startup is the expected signal for a provider that is unreachable — it is not a bug in the installation. Verify the provider pod is running and its endpoint is reachable. See Resilience for the state-machine details and recovery path. The breaker will transition to Half-Open after 60 seconds and close once 3 consecutive RPCs succeed.

Integration with GitOps¶

ArgoCD¶

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: virtrigaud
  namespace: argocd
spec:
  source:
    chart: virtrigaud
    repoURL: https://projectbeskar.github.io/virtrigaud
    targetRevision: "0.3.8"
    helm:
      values: |
        manager:
          image:
            tag: v0.3.8

Flux HelmRelease¶

apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: virtrigaud
  namespace: virtrigaud-system
spec:
  chart:
    spec:
      chart: virtrigaud
      version: "0.3.8"
      sourceRef:
        kind: HelmRepository
        name: virtrigaud
  values:
    manager:
      image:
        tag: v0.3.8

Migration from Kustomize to Helm¶

Back up existing resources:

kubectl get vms,providers,vmclasses,vmimages -A -o yaml > virtrigaud-backup.yaml

Remove Kustomize-managed resources (if safe to do so):

kubectl delete -k config/default

Install via Helm:

helm install virtrigaud virtrigaud/virtrigaud \
  --version 0.3.11 \
  --namespace virtrigaud-system \
  --create-namespace

Restore resources:

kubectl apply -f virtrigaud-backup.yaml