Sankofa/crossplane-provider-proxmox/README.md

# 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

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

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

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

### Provider Configuration

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

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

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

### Testing

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

### Running Locally

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