Sankofa/crossplane-provider-proxmox/MANUAL_TESTING.md

Manual Testing Guide

This guide provides step-by-step instructions for manually testing the Proxmox provider.

Prerequisites

• Kubernetes cluster with Crossplane installed
• Proxmox provider deployed
• ProviderConfig configured with valid credentials
• Access to Proxmox Web UI or API

Test Scenarios

1. Tenant Tags Verification

Objective: Verify tenant tags are correctly applied and filtered.

Steps

1. Create VM with tenant ID:

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-tenant"
    cpu: 2
    memory: "4Gi"
    disk: "50Gi"
    storage: "local-lvm"
    network: "vmbr0"
    image: "100"
    site: "us-sfvalley"
  providerConfigRef:
    name: proxmox-provider-config

2. Verify tag in Proxmox:

   • Log into Proxmox Web UI
   • Find the created VM
   • Check Tags field
   • Should show: tenant_test-tenant-123 (underscore, not colon)

3. Verify tenant filtering:

   • Use ListVMs() with tenant filter
   • Should only return VMs with matching tenant tag

4. Cleanup:

kubectl delete proxmoxvm test-vm-tenant

Expected Results:

• ✅ VM created with tag tenant_test-tenant-123
• ✅ Tag uses underscore separator
• ✅ Tenant filtering works correctly

---

2. API Adapter Authentication

Objective: Verify API authentication header format.

Steps

1. Check TypeScript adapter code:

   • Open api/src/adapters/proxmox/adapter.ts
   • Verify all 8 API calls use: Authorization: PVEAPIToken ${token}
   • Should NOT use: Authorization: PVEAPIToken=${token}

2. Test API calls:

   • Intercept network requests
   • Verify header format in all requests
   • Check all 8 endpoints:
     • getNodes()
     • getVMs()
     • getResource()
     • createResource()
     • updateResource()
     • deleteResource()
     • getMetrics()
     • healthCheck()

3. Verify error messages:

   • Test with invalid token
   • Verify clear error messages

Expected Results:

• ✅ All requests use correct header format (space, not equals)
• ✅ Authentication succeeds with valid token
• ✅ Clear error messages for auth failures

---

3. Proxmox Version Testing

Objective: Test compatibility across Proxmox versions.

Test on PVE 6.x

1. Verify importdisk API detection:

   • Create VM with cloud image
   • Check if importdisk is attempted
   • Verify graceful fallback if not supported

2. Check version detection:

   • Verify SupportsImportDisk() logic
   • Test error handling

Test on PVE 7.x

1. Verify importdisk API:

   • Should be supported
   • Test cloud image import

2. Test all features:

   • VM creation
   • Template cloning
   • Network validation

Test on PVE 8.x

1. Verify compatibility:
   • Test all features
   • Verify no breaking changes

Expected Results:

• ✅ Works correctly on all versions
• ✅ Graceful handling of API differences
• ✅ Appropriate error messages

---

4. Node Configuration Testing

Objective: Test multi-node deployments.

Steps

1. Test multiple nodes:

   • Deploy VMs to different nodes
   • Verify node selection works
   • Test node parameterization in compositions

2. Test node health checks:

   • Verify health check before VM creation
   • Test with unhealthy node
   • Verify appropriate error handling

3. Test node parameterization:

   • Use composition with node parameter
   • Verify node is set correctly

Expected Results:

• ✅ VMs deploy to correct nodes
• ✅ Health checks work correctly
• ✅ Parameterization works

---

5. Error Scenarios

Objective: Test error handling and recovery.

Test Cases

1. Node Unavailable:

   # Stop Proxmox node
   # Attempt to create VM
   # Verify error handling
   

2. Storage Full:

   # Fill storage to capacity
   # Attempt to create VM
   # Verify quota error
   

3. Network Bridge Missing:

   # Use non-existent bridge
   network: "vmbr999"
   # Verify validation error
   

4. Invalid Credentials:

   # Update ProviderConfig with wrong password
   # Verify authentication error
   

5. Quota Exceeded:

   # Request resources exceeding quota
   # Verify quota error
   

Expected Results:

• ✅ Appropriate error messages
• ✅ No retry on non-retryable errors
• ✅ Retry on transient errors
• ✅ Proper cleanup on failure

---

6. Network Bridge Validation

Objective: Verify network bridge validation works.

Steps

1. List available bridges:

   # Check bridges on node
   kubectl get proxmoxvm -o yaml | grep network
   

2. Test with existing bridge:

   network: "vmbr0"  # Should exist
   

   • Should succeed

3. Test with non-existent bridge:

   network: "vmbr999"  # Should not exist
   

   • Should fail with clear error

4. Verify validation timing:

   • Check that validation happens before VM creation
   • Verify error in status conditions

Expected Results:

• ✅ Validation happens before VM creation
• ✅ Clear error messages
• ✅ No partial VM creation

---

7. Validation Rules

Objective: Test all validation rules.

Test Cases

1. VM Name Validation:

   • Test valid names
   • Test invalid characters
   • Test length limits

2. Memory Validation:

   • Test minimum (128 MB)
   • Test maximum (2 TB)
   • Test various formats

3. Disk Validation:

   • Test minimum (1 GB)
   • Test maximum (100 TB)
   • Test various formats

4. CPU Validation:

   • Test minimum (1)
   • Test maximum (1024)

5. Image Validation:

   • Test template ID format
   • Test volid format
   • Test image name format

Expected Results:

• ✅ All validation rules enforced
• ✅ Clear error messages
• ✅ Appropriate validation timing

---

Test Checklist

Use this checklist to verify all functionality:

• Tenant tags created correctly
• Tenant filtering works
• API authentication works
• All 8 API endpoints work
• Works on PVE 6.x
• Works on PVE 7.x
• Works on PVE 8.x
• Multi-node deployment works
• Node health checks work
• Network bridge validation works
• All validation rules enforced
• Error handling works correctly
• Retry logic works
• Error messages are clear
• Status updates are accurate

---

Reporting Issues

When reporting test failures, include:

1. Test scenario: Which test failed
2. Steps to reproduce: Detailed steps
3. Expected behavior: What should happen
4. Actual behavior: What actually happened
5. Error messages: Full error output
6. Environment: Proxmox version, Kubernetes version, etc.
7. Logs: Relevant logs from controller and Proxmox

---

Success Criteria

All tests should:

• ✅ Complete without errors
• ✅ Produce expected results
• ✅ Have clear error messages when appropriate
• ✅ Clean up resources properly