Sankofa/docs/proxmox/DEVELOPMENT.md

Proxmox Provider - Development Guide

Development Environment Setup

Quick Setup

# Run automated setup
./scripts/setup-dev-environment.sh

# Or check dependencies manually
./scripts/check-dependencies.sh

Required Tools

• Go 1.21+ - For building the provider
• kubectl - For Kubernetes interaction
• make - For build automation
• Docker - For container builds (optional)

Optional Tools

• kind - For local Kubernetes testing
• yamllint - For YAML validation
• jq - For JSON processing
• terraform - For infrastructure as code

Building the Provider

Local Build

cd crossplane-provider-proxmox

# Build provider binary
make build

# Run tests
make test

# Generate CRDs
make manifests

# Format code
make fmt

# Run linter
make vet

Docker Build

cd crossplane-provider-proxmox

# Build container image
make docker-build

# Push to registry
make docker-push

Testing

Unit Tests

cd crossplane-provider-proxmox
make test

Integration Tests

# Deploy to kind cluster
kind create cluster --name proxmox-test

# Deploy provider
kubectl apply -f config/crd/bases/
kubectl apply -f config/provider.yaml

# Run integration tests
# (Add integration test suite)

Configuration Validation

# Validate all configuration files
./scripts/validate-configs.sh

Development Workflow

1. Make Changes

# Edit code in crossplane-provider-proxmox/pkg/
# Edit API definitions in crossplane-provider-proxmox/apis/

2. Generate Code

cd crossplane-provider-proxmox
make generate  # Generate DeepCopy methods
make manifests # Generate CRDs

3. Test Locally

# Build and test
make build
make test

# Run locally
make run

4. Validate

# Validate configurations
./scripts/validate-configs.sh

# Check dependencies
./scripts/check-dependencies.sh

5. Deploy to Test Cluster

# Deploy to kind
./scripts/deploy-crossplane-provider.sh

# Or manually
kubectl apply -f config/crd/bases/
kubectl apply -f config/provider.yaml

Project Structure

crossplane-provider-proxmox/
├── apis/                    # API definitions
│   └── v1alpha1/           # API version
├── pkg/                     # Provider implementation
│   ├── controller/         # Controllers
│   ├── proxmox/            # Proxmox API client
│   ├── metrics/            # Metrics collection
│   └── scaling/            # Auto-scaling logic
├── config/                  # Deployment manifests
│   ├── crd/                # CRD definitions
│   └── provider.yaml       # Provider deployment
├── examples/               # Example manifests
└── cmd/                    # Application entry point

Code Style

• Follow Go standard formatting (go fmt)
• Use golangci-lint for linting
• Write tests for all new functionality
• Document exported functions and types

Debugging

Provider Logs

# View provider logs
kubectl logs -n crossplane-system -l app=crossplane-provider-proxmox -f

# View specific pod logs
kubectl logs -n crossplane-system <pod-name> -f

Controller Logs

# View controller logs with debug level
kubectl logs -n crossplane-system -l app=crossplane-provider-proxmox --previous

API Client Debugging

Enable debug logging in the HTTP client:

• Set log level to DEBUG
• Enable request/response logging
• Check Proxmox API responses

CI/CD

GitHub Actions

The project includes GitHub Actions workflows:

• validate-configs.yml - Validates configuration files
• build-provider.yml - Builds and tests the provider

Pre-commit Hooks

Git hooks are automatically installed by setup-dev-environment.sh:

• Validates YAML syntax
• Checks for placeholders
• Runs configuration validation

Common Tasks

Add New Resource Type

1. Define API in apis/v1alpha1/
2. Generate code: make generate
3. Implement controller in pkg/controller/
4. Add Proxmox API methods in pkg/proxmox/
5. Create example manifest in examples/
6. Update documentation

Update API Client

1. Edit pkg/proxmox/client.go
2. Update HTTP client if needed
3. Add tests
4. Run: make test

Add Metrics

1. Define metrics in pkg/metrics/
2. Update collector
3. Add Prometheus queries
4. Update Grafana dashboards

Troubleshooting

Build Failures

# Clean and rebuild
cd crossplane-provider-proxmox
make clean
make build

Test Failures

# Run tests with verbose output
cd crossplane-provider-proxmox
go test -v ./...

CRD Generation Issues

# Regenerate CRDs
cd crossplane-provider-proxmox
make manifests

Related Documentation

• Deployment Guide
• Quick Start
• Task List