Development Guide¶

Welcome to the VirtRigaud development guide! This section provides information for developers who want to contribute to VirtRigaud or build custom providers.

Quick Links¶

GitHub Repository - Main project repository
Building Locally - Build VirtRigaud from source
Contributing Guide - How to contribute
Testing Locally - Test your changes
Provider Development - Create custom providers

Getting Started with Development¶

Prerequisites¶

To develop VirtRigaud, you'll need:

Go 1.23+ - Primary programming language
Docker - For building container images
Kubernetes cluster - kind, k3s, or remote cluster
kubectl - Kubernetes CLI
Helm 3.x - Package manager
make - Build automation

Quick Setup¶

# Clone the repository
git clone https://github.com/projectbeskar/virtrigaud.git
cd virtrigaud

# Install development dependencies
make dev-setup

# Run tests
make test

# Build binaries
make build

Development Workflows¶

Making Code Changes¶

Fork and clone the repository
Create a branch for your changes
Make your changes with tests
Run tests locally
Submit a pull request

See the Contributing Guide for detailed instructions.

API Development¶

When modifying API types (CRDs):

# Edit API types
vim api/infra.virtrigaud.io/v1beta1/virtualmachine_types.go

# Generate code and sync CRDs
make generate
make sync-helm-crds

# Verify everything is in sync
make verify-helm-crds

Provider Development¶

Creating a new provider for a hypervisor platform:

Read the Provider Development Tutorial
Implement the Provider interface
Add tests and documentation
Submit for provider catalog inclusion

Project Structure¶

virtrigaud/
├── api/                    # API definitions (CRDs)
│   └── infra.virtrigaud.io/
│       └── v1beta1/       # API version
├── cmd/                    # Main applications
│   ├── manager/           # Controller manager
│   └── provider-*/        # Provider binaries
├── internal/              # Internal packages
│   ├── controllers/       # Kubernetes controllers
│   ├── providers/         # Provider implementations
│   └── webhooks/          # Admission webhooks
├── pkg/                   # Public libraries
│   ├── grpc/             # gRPC interfaces
│   └── contracts/        # Provider contracts
├── config/               # Kustomize configs
│   ├── crd/             # CRD definitions
│   ├── manager/         # Manager deployment
│   └── webhook/         # Webhook configs
├── charts/              # Helm charts
│   └── virtrigaud/      # Main Helm chart
├── docs/                # Documentation source
└── test/                # Test suites

Building and Testing¶

Build Commands¶

# Build all binaries
make build

# Build specific component
make build-manager
make build-provider-vsphere

# Build container images
make docker-build
make docker-push

# Build Helm chart
make helm-package

Testing Commands¶

# Run unit tests
make test

# Run integration tests
make test-integration

# Run provider conformance tests
make test-vcts

# Run with coverage
make test-coverage

# Lint code
make lint

# Format code
make fmt

See Testing Locally for more details.

Documentation¶

Building Documentation¶

This documentation site is built with MkDocs. To build locally:

# Install dependencies
make install

# Install CRD documentation tools
make install-crd-tools

# Build documentation
make build

# Serve with live reload
make serve

See Building Locally for more information.

Documentation Structure¶

docs/
├── getting-started/     # Getting started guides
├── guides/             # Provider guides
├── providers/          # Provider documentation
├── examples/           # Example configurations
├── api-reference/      # API documentation
└── development/        # This section

Release Process¶

VirtRigaud follows semantic versioning (semver):

Major (v1.0.0): Breaking changes
Minor (v0.2.0): New features, backwards compatible
Patch (v0.2.1): Bug fixes

Creating a Release¶

Update version in relevant files
Generate changelog
Create git tag
Build and publish artifacts
Update Helm chart repository

See the Release Guide for details.

Community¶

Getting Help¶

GitHub Issues - Bug reports, feature requests
GitHub Discussions - Questions, ideas
Slack Channel - Real-time chat
Contributing Guide - How to contribute

Code of Conduct¶

VirtRigaud follows the CNCF Code of Conduct. Be respectful and inclusive.

Developer Resources¶

Key Documentation¶

Provider Contract - Provider interface specification
API Reference - CRD specifications
Architecture - System architecture
Security - Security considerations

Tools and Libraries¶

controller-runtime - Kubernetes controller framework
gRPC - Provider communication protocol
Kubebuilder - CRD and controller scaffolding
Helm - Package management
MkDocs - Documentation generation