Sankofa/crossplane-provider-proxmox

Crossplane Provider for Proxmox

A custom Crossplane provider that enables provisioning and management of Proxmox VE resources through Kubernetes.

Features

• Virtual Machine Management: Create, update, delete VMs
• Storage Management: Manage storage pools and volumes
• Network Management: Configure network bridges and interfaces
• Multi-Site Support: Manage multiple Proxmox clusters
• Status Reporting: Real-time VM status and IP addresses
• Reconciliation: Automatic drift detection and correction
• Retry Logic: Automatic retry for transient failures
• Error Handling: Comprehensive error handling and reporting

Architecture

crossplane-provider-proxmox/
├── apis/                    # CRD API definitions
│   └── v1alpha1/           # API version
├── pkg/                     # Provider implementation
│   ├── controller/         # Crossplane controllers
│   ├── proxmox/            # Proxmox API client
│   └── managed/            # Managed resource types
├── config/                 # Deployment manifests
│   └── crd/                # CRD definitions
└── examples/               # Usage examples

Installation

Prerequisites

• Kubernetes cluster with Crossplane installed
• Proxmox VE cluster with API access
• Go 1.21+ for building

Build and Install

# Build the provider
make build

# Install CRDs
kubectl apply -f config/crd/bases/

# Deploy the provider
kubectl apply -f config/provider.yaml

# Create ProviderConfig
kubectl apply -f examples/provider-config.yaml

Configuration

Module Path

IMPORTANT: Before building, update the module path in go.mod:

module github.com/yourorg/crossplane-provider-proxmox

Replace github.com/yourorg with your actual GitHub organization or module path.

Provider Configuration

apiVersion: proxmox.yourorg.io/v1alpha1
kind: ProviderConfig
metadata:
  name: proxmox-provider-config
spec:
  credentials:
    source: Secret
    secretRef:
      name: proxmox-credentials
      namespace: crossplane-system
      key: credentials.json
  sites:
    - name: us-east-1
      endpoint: https://pve1.yourdomain.com:8006
      node: pve1
    - name: eu-west-1
      endpoint: https://pve4.yourdomain.com:8006
      node: pve4

Create a Virtual Machine

apiVersion: proxmox.yourorg.io/v1alpha1
kind: ProxmoxVM
metadata:
  name: web-server-01
spec:
  forProvider:
    node: pve1
    name: web-server-01
    cpu: 4
    memory: 8Gi
    disk: 100Gi
    storage: local-lvm
    network: vmbr0
    image: ubuntu-22.04-cloud
    site: us-east-1
  providerConfigRef:
    name: proxmox-provider-config

API Reference

ProxmoxVM

Manages a Proxmox virtual machine.

Spec:

• node: Proxmox node to deploy on
• name: VM name
• cpu: Number of CPU cores
• memory: Memory size (e.g., "8Gi")
• disk: Disk size (e.g., "100Gi")
• storage: Storage pool name
• network: Network bridge
• image: OS template/image
• site: Site identifier

Status:

• vmId: Proxmox VM ID
• state: VM state (running, stopped, etc.)
• ipAddress: VM IP address
• conditions: Resource conditions

Error Handling and Retry Logic

The provider includes automatic retry logic for transient failures:

• Network Errors: Automatically retried with exponential backoff
• Temporary Errors: 502/503 errors are retried
• Max Retries: Configurable (default: 3)
• Backoff: Exponential with jitter, max 30 seconds

Development

Building

go mod download
go build -o bin/provider ./cmd/provider

Testing

go test ./...
go test -v -race -coverprofile=coverage.out ./...

Running Locally

# Set up local development environment
export PROXMOX_ENDPOINT=https://pve1.local:8006
export PROXMOX_USERNAME=root@pam
export PROXMOX_PASSWORD=your-password

# Run the provider
./bin/provider

License

Apache 2.0