docs: Migration analysis for kubebuilder rewrite

[kitsunoff]

Description

Comprehensive analysis document for migrating nixos-operator from KOPF (Python) to kubebuilder (Go).

Document Contents

1. Project Structure
2. Current Framework (KOPF)
3. CRD Definitions (Machine, NixosConfiguration)
4. Reconciliation Logic
5. Current Conditions Implementation
6. kstatus Compliance Issues
7. Recommended Status Schema
8. Additional Printer Columns
9. Controller Design Patterns
10. Configuration Variables
11. Prometheus Metrics
12. RBAC Requirements
13. Migration Checklist
14. SSH Connection Implementation
15. additionalFiles Processing
16. NixOS Apply Commands
17. Hardware Scanner Output
18. Input Validation Rules
19. Kubernetes Events
20. Example Resource Manifests
21. Error Handling Strategy
22. Long-Running Operations (Kubernetes Jobs)
23. Secret Watches with Field Indexes
24. Testing Strategy
25. Owner References and Garbage Collection
26. State Machines and Lifecycle
27. Leader Election and High Availability
28. (reserved)
29. Container Image Architecture

Location

docs/kubebuilder-migration-analysis.md

Recent Updates

• Machine addressing: Consolidated to single host field (was hostname/ipAddress)
• Per-machine concurrency: Added hasActiveJobForMachine() check and nio.homystack.com/machine label
• buildJobVolumes: Fixed ctx parameter in function signature
• Dockerfile: Removed unused nix-base stage, simplified to 2-stage build
• onRemoveFlake: State machine includes max 3 retries before proceeding with deletion
• Secret watches checklist: Removed contradictory cross-namespace item