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