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¶

Quick Start¶

Choose your provider and follow the setup guide:

1. vSphere Provider Guide - For VMware vSphere environments
2. Libvirt Provider Guide - For KVM/QEMU hosts
3. 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.

This is an abbreviated summary for v0.3.8. For the full authoritative matrix, see providers/providers-capabilities.md.

Advanced Topics¶

Once you're comfortable with basic provider setup:

• Advanced VM Lifecycle - Snapshots, reconfiguration, lifecycle hooks
• VM Cloning (VMClone) - Clone an existing VM into a new one (new in v0.3.8)
• 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 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 Documentation — vSphere, Libvirt, Proxmox
• Troubleshooting - Common issues
• Examples - Working configurations
• GitHub Issues - Report bugs or request features

Next Steps¶

1. Choose your provider from the list above
2. Follow the provider-specific setup guide
3. Create your first VM
4. Explore advanced features