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

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

```bash
kubectl apply -f my-vm.yaml
```

### Step 3: Verify Creation

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

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

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

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

### Stop VM

```bash
# Update VM resource or use Proxmox Web UI
```

### Delete VM

```bash
kubectl delete proxmoxvm my-vm
```

## Troubleshooting

### VM Creation Fails

1. **Check ProviderConfig**:
   ```bash
   kubectl get providerconfig proxmox-provider-config -o yaml
   ```

2. **Check Provider Logs**:
   ```bash
   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**:
   ```bash
   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](../proxmox/DEPLOYMENT_GUIDE.md)
- [Site Mapping](../proxmox/SITE_MAPPING.md)
- [Resource Inventory](../proxmox/RESOURCE_INVENTORY.md)