Sankofa/crossplane-provider-proxmox/docs/VALIDATION.md

# Validation Rules - Proxmox Provider

This document describes all validation rules enforced by the Proxmox provider.

## VM Name Validation

**Function**: `ValidateVMName()`

### Rules
- **Length**: 1-100 characters
- **Valid Characters**: Alphanumeric, hyphen (`-`), underscore (`_`), dot (`.`), space
- **Restrictions**: 
  - Cannot be empty
  - Cannot start or end with spaces
  - Spaces allowed in middle only

### Examples

✅ **Valid**:
- `"web-server-01"`
- `"vm.001"`
- `"my vm"`
- `"VM_001"`
- `"test-vm-name"`

❌ **Invalid**:
- `""` (empty)
- `" vm"` (starts with space)
- `"vm "` (ends with space)
- `"vm@001"` (invalid character `@`)
- `"vm#001"` (invalid character `#`)

---

## Memory Validation

**Function**: `ValidateMemory()`

### Rules
- **Required**: Yes
- **Format**: Supports multiple formats (case-insensitive)
  - `Gi`, `G` - Gibibytes
  - `Mi`, `M` - Mebibytes
  - `Ki`, `K` - Kibibytes
  - Plain number - Assumed MB
- **Range**: 128 MB - 2 TB (2,097,152 MB)

### Examples

✅ **Valid**:
- `"128Mi"` (minimum)
- `"4Gi"` (4 GiB = 4096 MB)
- `"8192Mi"` (8192 MB)
- `"4096"` (assumed MB)
- `"2Ti"` (2 TiB, converted to MB)

❌ **Invalid**:
- `""` (empty)
- `"127Mi"` (below minimum)
- `"2097153Mi"` (above maximum)
- `"invalid"` (invalid format)

---

## Disk Validation

**Function**: `ValidateDisk()`

### Rules
- **Required**: Yes
- **Format**: Supports multiple formats (case-insensitive)
  - `Ti`, `T` - Tebibytes
  - `Gi`, `G` - Gibibytes
  - `Mi`, `M` - Mebibytes
  - Plain number - Assumed GB
- **Range**: 1 GB - 100 TB (102,400 GB)

### Examples

✅ **Valid**:
- `"1Gi"` (minimum)
- `"50Gi"` (50 GB)
- `"100Gi"` (100 GB)
- `"1Ti"` (1 TiB = 1024 GB)
- `"100"` (assumed GB)

❌ **Invalid**:
- `""` (empty)
- `"0.5Gi"` (below minimum)
- `"102401Gi"` (above maximum)
- `"invalid"` (invalid format)

---

## CPU Validation

**Function**: `ValidateCPU()`

### Rules
- **Required**: Yes
- **Type**: Integer
- **Range**: 1-1024 cores
- **Default**: 2

### Examples

✅ **Valid**:
- `1` (minimum)
- `2`, `4`, `8`, `16`
- `1024` (maximum)

❌ **Invalid**:
- `0` (below minimum)
- `-1` (negative)
- `1025` (above maximum)

---

## Network Bridge Validation

**Function**: `ValidateNetworkBridge()`

### Rules
- **Required**: Yes
- **Format**: Alphanumeric, hyphen, underscore
- **Additional**: Bridge must exist on target node (validated at runtime)

### Examples

✅ **Valid**:
- `"vmbr0"`
- `"vmbr1"`
- `"custom-bridge"`
- `"bridge_01"`
- `"BRIDGE"`

❌ **Invalid**:
- `""` (empty)
- `"vmbr 0"` (contains space)
- `"vmbr@0"` (invalid character)
- `"vmbr.0"` (dot typically not used)

---

## Image Specification Validation

**Function**: `ValidateImageSpec()`

### Rules
- **Required**: Yes
- **Formats**: Three formats supported

#### 1. Template VMID (Numeric)
- **Range**: 100-999999999
- **Example**: `"100"`, `"1000"`

#### 2. Volume ID (Volid Format)
- **Format**: `storage:path/to/image`
- **Requirements**: 
  - Must contain `:`
  - Storage name before `:` cannot be empty
  - Path after `:` cannot be empty
- **Example**: `"local:iso/ubuntu-22.04.iso"`

#### 3. Image Name
- **Length**: 1-255 characters
- **Format**: Alphanumeric, hyphen, underscore, dot
- **Example**: `"ubuntu-22.04-cloud"`

### Examples

✅ **Valid**:
- `"100"` (template VMID)
- `"local:iso/ubuntu-22.04.iso"` (volid)
- `"ubuntu-22.04-cloud"` (image name)

❌ **Invalid**:
- `""` (empty)
- `"99"` (VMID too small)
- `"1000000000"` (VMID too large)
- `":path"` (missing storage)
- `"storage:"` (missing path)

---

## VMID Validation

**Function**: `ValidateVMID()`

### Rules
- **Range**: 100-999999999
- **Type**: Integer

### Examples

✅ **Valid**:
- `100` (minimum)
- `1000`, `10000`
- `999999999` (maximum)

❌ **Invalid**:
- `99` (below minimum)
- `0`, `-1` (invalid)
- `1000000000` (above maximum)

---

## Validation Timing

Validation occurs at multiple stages:

1. **Controller Validation**: Before VM creation
   - All input validation functions are called
   - Errors reported via Kubernetes Conditions
   - VM creation blocked if validation fails

2. **Runtime Validation**: During VM creation
   - Network bridge existence checked
   - Storage availability verified
   - Node health checked

3. **API Validation**: Proxmox API validation
   - Proxmox may reject invalid configurations
   - Errors reported and handled appropriately

---

## Error Messages

Validation errors include:
- **Clear error messages** describing what's wrong
- **Expected values** when applicable
- **Suggestions** for fixing issues

Example:
```
Error: memory 64Mi (64 MB) is below minimum of 128 MB
```

---

## Best Practices

1. **Validate Early**: Check configurations before deployment
2. **Use Clear Names**: Follow VM naming conventions
3. **Verify Resources**: Ensure network bridges and storage exist
4. **Check Quotas**: Verify resource limits before creation
5. **Monitor Errors**: Watch for validation failures in status conditions