Update .gitignore, remove package-lock.json, and enhance Cloudflare and Proxmox adapters
- Added lock file exclusions for pnpm in .gitignore. - Removed obsolete package-lock.json from the api and portal directories. - Enhanced Cloudflare adapter with additional interfaces for zones and tunnels. - Improved Proxmox adapter error handling and logging for API requests. - Updated Proxmox VM parameters with validation rules in the API schema. - Enhanced documentation for Proxmox VM specifications and examples.
This commit is contained in:
defiQUG
249
crossplane-provider-proxmox/docs/VALIDATION.md
Normal file
249
crossplane-provider-proxmox/docs/VALIDATION.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user