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.
2025-12-12 19:29:01 -08:00
parent 9daf1fd378
commit 7cd7022f6e
66 changed files with 5892 additions and 14502 deletions
--- a/crossplane-provider-proxmox/docs/TESTING.md
+++ b/crossplane-provider-proxmox/docs/TESTING.md
@@ -0,0 +1,227 @@
+# Testing Guide - Proxmox Provider
+
+This document provides guidance for testing the Crossplane Proxmox provider.
+
+## Unit Tests
+
+### Running Unit Tests
+
+```bash
+# Run all unit tests
+go test ./pkg/...
+
+# Run tests for specific package
+go test ./pkg/utils/...
+go test ./pkg/proxmox/...
+go test ./pkg/controller/virtualmachine/...
+
+# Run with coverage
+go test -cover ./pkg/...
+
+# Generate coverage report
+go test -coverprofile=coverage.out ./pkg/...
+go tool cover -html=coverage.out
+```
+
+### Test Files
+
+- `pkg/utils/parsing_test.go` - Parsing utility tests
+- `pkg/utils/validation_test.go` - Validation function tests
+- `pkg/proxmox/networks_test.go` - Network API tests
+- `pkg/proxmox/client_tenant_test.go` - Tenant tag format tests
+- `pkg/controller/virtualmachine/errors_test.go` - Error categorization tests
+
+## Integration Tests
+
+Integration tests require a Proxmox test environment.
+
+### Prerequisites
+
+1. Proxmox VE cluster with API access
+2. Valid API credentials
+3. Test node with available resources
+4. Test storage pools
+5. Network bridges configured
+
+### Running Integration Tests
+
+```bash
+# Run integration tests
+go test -tags=integration ./pkg/controller/virtualmachine/...
+
+# Skip integration tests (run unit tests only)
+go test -short ./pkg/...
+```
+
+### Integration Test Scenarios
+
+1. **VM Creation with Template Cloning**
+   - Requires: Template VM (VMID 100-999999999)
+   - Tests: Template clone functionality
+
+2. **VM Creation with Cloud Image Import**
+   - Requires: Cloud image in storage, importdisk API support
+   - Tests: Image import functionality
+
+3. **VM Creation with Pre-imported Images**
+   - Requires: Pre-imported image in storage
+   - Tests: Image reference functionality
+
+4. **Multi-Site Deployment**
+   - Requires: Multiple Proxmox sites configured
+   - Tests: Site selection and validation
+
+5. **Network Bridge Validation**
+   - Requires: Network bridges on test nodes
+   - Tests: Network existence validation
+
+6. **Error Recovery**
+   - Tests: Retry logic and error handling
+
+7. **Cloud-init Configuration**
+   - Requires: Cloud-init support
+   - Tests: UserData writing and configuration
+
+## Manual Testing
+
+### Prerequisites
+
+- Kubernetes cluster with Crossplane installed
+- Proxmox provider deployed
+- ProviderConfig configured
+- Valid credentials
+
+### Test Scenarios
+
+#### 1. Tenant Tags
+
+```bash
+# Create VM with tenant ID
+kubectl apply -f - <<EOF
+apiVersion: proxmox.sankofa.nexus/v1alpha1
+kind: ProxmoxVM
+metadata:
+  name: test-vm-tenant
+  labels:
+    tenant-id: "test-tenant-123"
+spec:
+  forProvider:
+    node: "test-node"
+    name: "test-vm"
+    cpu: 2
+    memory: "4Gi"
+    disk: "50Gi"
+    storage: "local-lvm"
+    network: "vmbr0"
+    image: "100"
+    site: "test-site"
+  providerConfigRef:
+    name: proxmox-provider-config
+EOF
+
+# Verify tenant tag in Proxmox
+# Should see tag: tenant_test-tenant-123
+```
+
+#### 2. API Adapter Authentication
+
+Test the TypeScript API adapter authentication:
+
+```bash
+# Verify authentication header format
+# Should use: Authorization: PVEAPIToken ${token}
+# NOT: Authorization: PVEAPIToken=${token}
+```
+
+#### 3. Proxmox Version Testing
+
+Test on different Proxmox versions:
+- PVE 6.x
+- PVE 7.x
+- PVE 8.x
+
+Verify importdisk API detection works correctly.
+
+#### 4. Node Configuration Testing
+
+- Test with multiple nodes
+- Test node health checks
+- Test node parameterization in compositions
+
+#### 5. Error Scenarios
+
+Test various error conditions:
+- Node unavailable
+- Storage full
+- Network bridge missing
+- Invalid credentials
+- Quota exceeded
+
+## Test Data Setup
+
+### Creating Test Templates
+
+1. Create a VM in Proxmox
+2. Install OS and configure
+3. Convert to template
+4. Note the VMID
+
+### Creating Test Images
+
+1. Download cloud image (e.g., Ubuntu cloud image)
+2. Upload to Proxmox storage
+3. Note the storage and path
+
+### Network Bridges
+
+Ensure test nodes have:
+- `vmbr0` (default bridge)
+- Additional bridges for testing
+
+## Troubleshooting Tests
+
+### Common Issues
+
+1. **Authentication Failures**
+   - Verify credentials in ProviderConfig
+   - Check API token format
+   - Verify Proxmox API access
+
+2. **Network Connectivity**
+   - Verify network bridges exist
+   - Check node connectivity
+   - Verify firewall rules
+
+3. **Storage Issues**
+   - Verify storage pools exist
+   - Check available space
+   - Verify storage permissions
+
+4. **Test Environment**
+   - Verify test namespace exists
+   - Check RBAC permissions
+   - Verify CRDs are installed
+
+## Continuous Integration
+
+Tests should be run in CI/CD pipeline:
+
+```yaml
+# Example CI configuration
+test:
+  unit:
+    - go test -v -short ./pkg/...
+  integration:
+    - go test -v -tags=integration ./pkg/controller/virtualmachine/...
+  coverage:
+    - go test -coverprofile=coverage.out ./pkg/...
+```
+
+## Best Practices
+
+1. **Isolation**: Use separate test namespaces
+2. **Cleanup**: Always clean up test resources
+3. **Idempotency**: Tests should be repeatable
+4. **Mocking**: Use mocks for external dependencies
+5. **Coverage**: Aim for >80% code coverage
+
--- a/crossplane-provider-proxmox/docs/VALIDATION.md
+++ b/crossplane-provider-proxmox/docs/VALIDATION.md
@@ -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
+