Operations Guide¶

Operator-facing reference for running VirtRigaud v0.3.8 in production. The pages linked from here are the authoritative source for each topic; this index is a router, not a duplicate.

Core operational topics¶

Security sub-pages¶

The detailed control-by-control pages live under providers/security/ because they apply equally to in-tree providers and external providers built on the SDK. They are kept honest about what is and is not wired:

• Bearer Token Authentication — Production-relevant for hypervisor API tokens (Proxmox today, future REST-based providers). gRPC-channel bearer auth via the SDK exists but is still not enabled by the in-tree providers and not sent by the manager.
• mTLS Configuration — Wired and enforced since v0.3.7 (#147). Every Provider CR now requires a spec.runtime.service.tls block (or an explicit, audit-flagged opt-out); see the Upgrade Guide for the migration steps.
• External Secrets — Wiring External Secrets Operator / Vault into the credentials Secret that VirtRigaud mounts.
• Network Policies — Still a recommended defence-in-depth control and the compensating control for the unwired gRPC bearer-auth path (#148).

Infrastructure-specific topics¶

Production-readiness checklist¶

Use this before promoting a VirtRigaud deployment to production. Each item links to the page that actually covers it.

• CRDs installed at the v0.3.8 schema — helm pull virtrigaud/virtrigaud --version 0.3.11 --untar && kubectl apply -f virtrigaud/crds/. See Upgrade Guide.
• Manager + provider images pinned to v0.3.8 — release artifacts are tagged in lockstep; do not mix versions across the manager/providers/CRDs trio.
• Metrics scrape configured — a ServiceMonitor (or equivalent) against the manager's /metrics. Expect the families documented in Observability, including the v0.3.8 kind="VMClone"/kind="VMSet" reconcile series.
• mTLS configured on every Provider CR — enforced since v0.3.7 (#147). A Provider without a spec.runtime.service.tls block (or an explicit, audit-flagged opt-out) will not reconcile. See mTLS and the Upgrade Guide.
• Per-Provider CircuitBreaker behavior understood — read Resilience. The CB will trip Open within seconds of a provider going bad. That is the metric working as designed.
• Compensating network controls for the unwired gRPC bearer-auth path (#148) — NetworkPolicy that restricts provider-pod ingress to the manager pod, complementing the now-wired mTLS. See Bearer Token and Network Policies.
• Provider credentials reviewed — for Proxmox, API tokens (token_id / token_secret) must be used; password fallback is for development parity only. See Bearer Token Authentication.
• Secrets backend chosen — at minimum, kube-apiserver EncryptionConfiguration for etcd-at-rest encryption. For multi-cluster / regulated deployments, External Secrets Operator (Vault, AWS Secrets Manager, etc.) per External Secrets.
• Manager HA — manager Deployment with at least 2 replicas and leader election (controller-runtime enables it by default).
• Audit trail — CHANGELOG entries with author attribution per CLAUDE.md (regulated-deployment posture), plus K8s audit logging enabled at the cluster level.
• Backup/restore procedure — VirtRigaud does not back up CRs; reuse your standard etcd snapshot + cluster-level Velero / equivalent.

Day-2 cheatsheet¶

The commands below are the same patterns the Observability and Security pages cite; they live here as a quick-reference. Provider workloads in v0.3.8 are operator-deployed via Helm with the chart's provider sub-charts (or applied directly as Deployments referenced by a Provider CR). Note that as of v0.3.8 the chart's templated providers are disabled by default (#173) — CR-managed providers are unaffected; set providers.<type>.enabled=true if you rely on templated providers. The labels below assume the chart's defaults.

Inspect Provider CR state¶

# All Provider CRs and their reconcile state
kubectl get providers.infra.virtrigaud.io -A

# Detailed view of a provider (events, conditions, last-seen credentials)
kubectl describe provider.infra.virtrigaud.io <name>

Inspect VirtualMachine state¶

kubectl get virtualmachines.infra.virtrigaud.io -A

# Watch a single VM through reconciliation
kubectl get virtualmachines.infra.virtrigaud.io my-vm -w

# Events for a VM
kubectl get events --field-selector involvedObject.kind=VirtualMachine,involvedObject.name=my-vm

Manager / provider logs¶

# Manager logs
kubectl logs -n virtrigaud-system deploy/virtrigaud-manager

# Provider pod logs (label depends on chart values; this matches the default sub-chart)
kubectl logs -n virtrigaud-system -l app.kubernetes.io/component=provider --tail=200

Rotating provider credentials¶

The credentials Secret is mounted read-only as files under /etc/virtrigaud/credentials/ inside each provider pod (internal/controller/provider_controller.go). After updating the Secret, restart the provider Deployment so it re-reads the files:

kubectl -n virtrigaud-system patch secret <provider-creds> \
  -p '{"stringData":{"password":"<NEW>"}}'

# Restart so the file mount picks up the new value
kubectl -n virtrigaud-system rollout restart deploy/<provider-deployment>

Reading CircuitBreaker state¶

The G6 wiring (since v0.3.6) exposes one breaker per Provider CR. The fast operator signal is:

kubectl exec -n virtrigaud-system deploy/virtrigaud-manager -- \
  curl -s localhost:8080/metrics | \
  grep -E 'virtrigaud_circuit_breaker_(state|failures_total)'

state == 1 is Open; state == 2 is Half-Open; state == 0 is Closed. See Resilience.

What this section does NOT cover¶

• In-cluster networking design — VirtRigaud does not ship a CNI choice or an Ingress recommendation; pick one that meets your security posture and follow its documentation.
• Hypervisor administration — vCenter capacity planning, libvirt host hardening at the OS level, Proxmox cluster maintenance: not in scope.
• Application-level VM ops — patching guest OS, monitoring guest applications: out of scope; VirtRigaud manages the VM lifecycle, not what runs inside.

Next steps¶

• New operator? Start at the Quickstart, then read Security and Resilience before promoting to production.
• Upgrading from a previous release? Use the Upgrade Guide.
• Investigating an incident? Observability lists every virtrigaud_* metric and what it tells you.