Sankofa/docs/runbooks/PROXMOX_VM_PROVISIONING.md

Proxmox VM Provisioning Runbook

Overview

This runbook provides step-by-step procedures for provisioning virtual machines on Proxmox infrastructure using the Crossplane provider.

Prerequisites

• Kubernetes cluster with Crossplane and Proxmox provider installed
• ProviderConfig configured and ready
• Appropriate permissions to create ProxmoxVM resources
• Access to Proxmox Web UI (for verification)

Standard VM Provisioning

Step 1: Create VM Manifest

Create a YAML manifest for the VM:

apiVersion: proxmox.sankofa.nexus/v1alpha1
kind: ProxmoxVM
metadata:
  name: my-vm
  namespace: default
spec:
  forProvider:
    node: ML110-01
    name: my-vm
    cpu: 2
    memory: 4Gi
    disk: 50Gi
    storage: local-lvm
    network: vmbr0
    image: ubuntu-22.04-cloud
    site: us-sfvalley
    userData: |
      #cloud-config
      users:
        - name: admin
          groups: sudo
          shell: /bin/bash
          sudo: ['ALL=(ALL) NOPASSWD:ALL']
  providerConfigRef:
    name: proxmox-provider-config

Step 2: Apply Manifest

kubectl apply -f my-vm.yaml

Step 3: Verify Creation

# Check VM resource status
kubectl get proxmoxvm my-vm

# Get detailed status
kubectl describe proxmoxvm my-vm

# Check VM in Proxmox
# Log into Proxmox Web UI and verify VM exists

Step 4: Verify VM Status

Wait for VM to be created and check status:

# Watch VM status
kubectl get proxmoxvm my-vm -w

# Check VM ID
kubectl get proxmoxvm my-vm -o jsonpath='{.status.vmId}'

# Check VM state
kubectl get proxmoxvm my-vm -o jsonpath='{.status.state}'

# Check IP address (if available)
kubectl get proxmoxvm my-vm -o jsonpath='{.status.ipAddress}'

Multi-Site VM Provisioning

Provision VM on Different Site

Update the site field in the manifest:

spec:
  forProvider:
    site: eu-west-1  # or apac-1 or us-sfvalley
    node: R630-01   # for both eu-west-1 and apac-1

VM Lifecycle Operations

Start VM

# VM should start automatically after creation
# To manually start, update the VM resource or use Proxmox API

Stop VM

# Update VM resource or use Proxmox Web UI

Delete VM

kubectl delete proxmoxvm my-vm

Troubleshooting

VM Creation Fails

1. Check ProviderConfig:

   kubectl get providerconfig proxmox-provider-config -o yaml
   

2. Check Provider Logs:

   kubectl logs -n crossplane-system -l app=crossplane-provider-proxmox --tail=50
   

3. Verify Site Configuration:

   • Check if site exists in ProviderConfig
   • Verify endpoint is reachable
   • Check node name matches actual Proxmox node

4. Check Proxmox Resources:

   • Verify storage pool exists
   • Verify network bridge exists
   • Verify OS template exists

VM Stuck in Creating State

1. Check VM Resource Events:

   kubectl describe proxmoxvm my-vm
   

2. Check Proxmox Web UI:

   • Log into Proxmox
   • Check if VM exists
   • Check VM status
   • Review Proxmox logs

3. Verify Resources:

   • Check available storage
   • Check available memory
   • Check node status

VM Not Getting IP Address

1. Check Cloud-Init:

   • Verify userData is correct
   • Check cloud-init logs in VM

2. Check Network Configuration:

   • Verify network bridge is correct
   • Check DHCP configuration
   • Verify VM network interface

3. Check Guest Agent:

   • Ensure QEMU guest agent is installed
   • Verify guest agent is running

Best Practices

1. Resource Naming: Use descriptive names for VMs
2. Resource Limits: Set appropriate CPU and memory limits
3. Storage Planning: Choose appropriate storage pools
4. Network Configuration: Use correct network bridges
5. Backup Strategy: Configure backups for important VMs
6. Monitoring: Set up monitoring for VM metrics

Common Configurations

Small VM (Development)

• CPU: 1-2 cores
• Memory: 2-4 Gi
• Disk: 20-50 Gi

Medium VM (Staging)

• CPU: 2-4 cores
• Memory: 4-8 Gi
• Disk: 50-100 Gi

Large VM (Production)

• CPU: 4+ cores
• Memory: 8+ Gi
• Disk: 100+ Gi

Related Documentation

• Deployment Guide
• Site Mapping
• Resource Inventory