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:

```bash
cd crossplane-provider-proxmox
make build
```

Or build Docker image:

```bash
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

```bash
# 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:

```bash
./scripts/deploy-proxmox-provider.sh
```

## Step 3: Deploy Provider

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

Verify deployment:

```bash
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

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

### Option 2: API Token (Recommended)

```bash
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:

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

Verify ProviderConfig:

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

## Step 6: Verify Provider Connectivity

Check provider logs:

```bash
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:

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

Check VM status:

```bash
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:
   ```bash
   kubectl describe pod -n crossplane-system -l app=crossplane-provider-proxmox
   ```

2. Check logs:
   ```bash
   kubectl logs -n crossplane-system -l app=crossplane-provider-proxmox
   ```

3. Verify image exists:
   ```bash
   kubectl get deployment -n crossplane-system crossplane-provider-proxmox -o yaml | grep image
   ```

### Authentication Failures

1. Verify credentials secret:
   ```bash
   kubectl get secret proxmox-credentials -n crossplane-system -o yaml
   ```

2. Test credentials manually:
   ```bash
   curl -k -X POST \
     -d "username=root@pam&password=your-password" \
     https://your-proxmox:8006/api2/json/access/ticket
   ```

3. Check ProviderConfig:
   ```bash
   kubectl get providerconfig proxmox-provider-config -n crossplane-system -o yaml
   ```

### VM Creation Failures

1. Check VM resource status:
   ```bash
   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)
   ```bash
   ./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](./TASK_LIST.md)
- [Site Mapping](./SITE_MAPPING.md)
- [Resource Inventory](./RESOURCE_INVENTORY.md)
- [Completion Summary](./COMPLETION_SUMMARY.md)