VirtRigaud Provider Guides¶

This section provides step-by-step guides for working with VirtRigaud providers.

What is a Provider?¶

A Provider is VirtRigaud's connection to your hypervisor infrastructure. It acts as a bridge between Kubernetes and your virtualization platform (vSphere, Libvirt/KVM, or Proxmox VE), translating Kubernetes resource definitions into actual virtual machines.

Think of providers as plugins that enable VirtRigaud to manage VMs on different platforms. Each provider:

Authenticates with your hypervisor
Translates VirtRigaud resource specs to platform-specific configurations
Manages VM lifecycle (create, delete, power operations)
Reports VM status back to Kubernetes

Provider Architecture¶

VirtRigaud uses a Remote Provider architecture where each provider runs as an independent service:

┌─────────────────────────────────────────┐
│         Kubernetes Cluster               │
│  ┌──────────────────────────────────┐   │
│  │   VirtRigaud Manager             │   │
│  │   (Controller)                   │   │
│  └─────────┬────────────────────────┘   │
│            │ gRPC                        │
│            │                             │
│  ┌─────────▼────────────────────────┐   │
│  │   Provider Pod                   │   │
│  │   (vSphere/Libvirt/Proxmox)      │   │
│  └─────────┬────────────────────────┘   │
└────────────┼──────────────────────────────┘
             │ API calls
             │
        ┌────▼─────┐
        │Hypervisor│
        └──────────┘

Benefits of this architecture:

Isolation: Provider failures don't crash the manager
Scalability: Scale providers independently
Security: Credentials stay in provider pods
Flexibility: Mix multiple provider versions

Supported Providers¶

Provider	Status	Best For	Features
vSphere	Production	Enterprise environments	Full reconfiguration, snapshots, cloning, templates
Libvirt	Production	Development, edge computing	Cloud-init, VNC console, local/remote hosts
Proxmox VE	Production	Cost-effective virtualization	API token auth, guest agent, templates

Quick Start¶

Choose your provider and follow the setup guide:

vSphere Provider Guide - For VMware vSphere environments
Libvirt Provider Guide - For KVM/QEMU hosts
Proxmox Provider Guide - For Proxmox VE clusters

Each guide covers:

Prerequisites and requirements
Authentication setup
Provider configuration
First VM creation
Troubleshooting tips

Provider Capabilities Matrix¶

Not all providers support the same features. See the Provider Capabilities Matrix for a detailed comparison.

Feature	vSphere	Libvirt	Proxmox
VM Creation	✅	✅	✅
Power Management	✅	✅	✅
Reconfiguration	✅	✅	✅
Snapshots	✅	✅	✅
Cloning	✅	✅	✅
Templates	✅	✅	✅
Console Access	❌	✅ (VNC)	✅ (VNC)
Cloud-init	✅	✅	✅
Guest Agent	✅	✅	✅
Storage Policies	✅	❌	❌
DRS/HA	✅	❌	✅

Advanced Topics¶

Once you're comfortable with basic provider setup:

Advanced VM Lifecycle - Snapshots, cloning, reconfiguration
Nested Virtualization - Running hypervisors in VMs
Graceful Shutdown - Proper VM shutdown handling
Remote Providers - Provider architecture deep dive

Developing Custom Providers¶

Want to add support for a new hypervisor?

Provider Development Tutorial - Step-by-step guide
Provider API Reference - Technical documentation
Provider Versioning - Version management

Multi-Provider Deployments¶

VirtRigaud can manage multiple providers simultaneously:

# Production vSphere
apiVersion: infra.virtrigaud.io/v1beta1
kind: Provider
metadata:
  name: vsphere-prod
spec:
  type: vsphere
  # ... vSphere config

---
# Development Libvirt
apiVersion: infra.virtrigaud.io/v1beta1
kind: Provider
metadata:
  name: libvirt-dev
spec:
  type: libvirt
  # ... Libvirt config

Each VM can specify which provider to use via spec.providerRef.

Security Considerations¶

When setting up providers, consider:

Credential management: Use Kubernetes secrets, never hardcode credentials
Least privilege: Grant minimal required permissions
Network isolation: Use NetworkPolicies to restrict provider communication
Secret management: Consider External Secrets Operator
mTLS: Enable mutual TLS for production deployments

See the Security Guide for detailed recommendations.

Getting Help¶

Provider-Specific Guides - Detailed provider documentation
Troubleshooting - Common issues
Examples - Working configurations
GitHub Issues - Report bugs or request features
Slack Channel - Community support

Next Steps¶

Choose your provider from the list above
Follow the provider-specific setup guide
Create your first VM
Explore advanced features