Sankofa/docs/proxmox/guides/DEPLOYMENT_GUIDE.md

Proxmox Provider Deployment Guide

This guide provides step-by-step instructions for deploying the Proxmox Crossplane provider.

Prerequisites

Required

• Kubernetes cluster with Crossplane installed
• kubectl configured to access the cluster
• Proxmox VE cluster with API access
• Credentials for Proxmox (username/password or API token)

Optional

• Go 1.21+ (for building from source)
• Docker (for building container images)
• Make (for using Makefile)

Step 1: Build Provider (Optional)

If building from source:

cd crossplane-provider-proxmox
make build

Or build Docker image:

make docker-build
docker tag crossplane-provider-proxmox:latest ghcr.io/sankofa/crossplane-provider-proxmox:latest
docker push ghcr.io/sankofa/crossplane-provider-proxmox:latest

Step 2: Deploy CRDs

# Generate CRDs (if not already generated)
cd crossplane-provider-proxmox
make manifests

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

Or use the deployment script:

./scripts/deploy-proxmox-provider.sh

Step 3: Deploy Provider

kubectl apply -f crossplane-provider-proxmox/config/provider.yaml

Verify deployment:

kubectl get deployment -n crossplane-system crossplane-provider-proxmox
kubectl get pods -n crossplane-system -l app=crossplane-provider-proxmox

Step 4: Create Credentials Secret

Option 1: Username/Password

kubectl create secret generic proxmox-credentials \
  --from-literal=credentials.json='{"username":"root@pam","password":"your-password"}' \
  -n crossplane-system

Option 2: API Token (Recommended)

kubectl create secret generic proxmox-credentials \
  --from-literal=credentials.json='{"username":"root@pam","token":"root@pam!token-name=token-secret"}' \
  -n crossplane-system

Step 5: Create ProviderConfig

Update crossplane-provider-proxmox/examples/provider-config.yaml with your actual endpoints and sites, then apply:

kubectl apply -f crossplane-provider-proxmox/examples/provider-config.yaml

Verify ProviderConfig:

kubectl get providerconfig -n crossplane-system
kubectl describe providerconfig proxmox-provider-config -n crossplane-system

Step 6: Verify Provider Connectivity

Check provider logs:

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

Look for:

• Successful authentication messages
• No connection errors
• Provider ready status

Step 7: Test VM Creation

Create a test VM:

kubectl apply -f crossplane-provider-proxmox/examples/test-vm-instance-1.yaml

Check VM status:

kubectl get proxmoxvm test-vm-instance-1
kubectl describe proxmoxvm test-vm-instance-1

Verify in Proxmox:

• Log into Proxmox Web UI
• Check if VM was created
• Verify VM configuration

Troubleshooting

Provider Not Starting

1. Check pod status:

   kubectl describe pod -n crossplane-system -l app=crossplane-provider-proxmox
   

2. Check logs:

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

3. Verify image exists:

   kubectl get deployment -n crossplane-system crossplane-provider-proxmox -o yaml | grep image
   

Authentication Failures

1. Verify credentials secret:

   kubectl get secret proxmox-credentials -n crossplane-system -o yaml
   

2. Test credentials manually:

   curl -k -X POST \
     -d "username=root@pam&password=your-password" \
     https://your-proxmox:8006/api2/json/access/ticket
   

3. Check ProviderConfig:

   kubectl get providerconfig proxmox-provider-config -n crossplane-system -o yaml
   

VM Creation Failures

1. Check VM resource status:

   kubectl describe proxmoxvm <vm-name>
   

2. Verify site configuration:

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

3. Check Proxmox logs:

   • Log into Proxmox Web UI
   • Check system logs for errors
   • Verify storage pools and networks exist

Verification Checklist

• CRDs deployed successfully
• Provider pod is running
• Provider logs show no errors
• Credentials secret created
• ProviderConfig created and ready
• Test VM creation successful
• VM appears in Proxmox Web UI
• VM status updates correctly

Next Steps

After successful deployment:

1. Deploy Prometheus Exporters (TASK-012)

   ./scripts/setup-proxmox-agents.sh --site us-sfvalley --node ML110-01
   

2. Configure Cloudflare Tunnels (TASK-013)

   • Generate tunnel credentials
   • Deploy tunnel configs to nodes

3. Set Up Monitoring (TASK-014)

   • Import Grafana dashboards
   • Configure alerts

4. Test Multi-Site (TASK-016)

   • Deploy VMs to different sites
   • Verify cross-site operations

Additional Resources

• Task List
• Site Mapping
• Resource Inventory
• Completion Summary