# Proxmox Provider - Development Guide

## Development Environment Setup

### Quick Setup

```bash
# 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

```bash
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

```bash
cd crossplane-provider-proxmox

# Build container image
make docker-build

# Push to registry
make docker-push
```

## Testing

### Unit Tests

```bash
cd crossplane-provider-proxmox
make test
```

### Integration Tests

```bash
# 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

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

## Development Workflow

### 1. Make Changes

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

### 2. Generate Code

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

### 3. Test Locally

```bash
# Build and test
make build
make test

# Run locally
make run
```

### 4. Validate

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

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

### 5. Deploy to Test Cluster

```bash
# 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

```bash
# 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

```bash
# 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

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

### Test Failures

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

### CRD Generation Issues

```bash
# Regenerate CRDs
cd crossplane-provider-proxmox
make manifests
```

## Related Documentation

- [Deployment Guide](../proxmox/DEPLOYMENT_GUIDE.md)
- [Quick Start](../proxmox/QUICK_START.md)
- [Task List](../proxmox/TASK_LIST.md)