9daf1fd378
- Add comprehensive database migrations (001-024) for schema evolution - Enhance API schema with expanded type definitions and resolvers - Add new middleware: audit logging, rate limiting, MFA enforcement, security, tenant auth - Implement new services: AI optimization, billing, blockchain, compliance, marketplace - Add adapter layer for cloud integrations (Cloudflare, Kubernetes, Proxmox, storage) - Update Crossplane provider with enhanced VM management capabilities - Add comprehensive test suite for API endpoints and services - Update frontend components with improved GraphQL subscriptions and real-time updates - Enhance security configurations and headers (CSP, CORS, etc.) - Update documentation and configuration files - Add new CI/CD workflows and validation scripts - Implement design system improvements and UI enhancements
267 lines
4.8 KiB
Markdown
267 lines
4.8 KiB
Markdown
# 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)
|
|
|