feat: ReaperOverlay CRD for overlay lifecycle management

[miguelgila]

Summary

• Adds ReaperOverlay CRD — a PVC-like resource that decouples overlay lifecycle from pod lifecycle
• Enables Kubernetes-native overlay creation, inspection, reset, and deletion without requiring direct node access
• ReaperPods with overlayName now block (stay Pending) until a matching ReaperOverlay exists and is Ready, like Pods with unbound PVCs

Changes

CRD (src/crds/reaper_overlay.rs)

• ReaperOverlaySpec: resetPolicy (Manual/OnFailure/OnDelete), resetGeneration (monotonic counter)
• ReaperOverlayStatus: phase, observedResetGeneration, per-node status array, message
• Generated CRD YAML in deploy/kubernetes/crds/ and deploy/helm/reaper/crds/

Controller (src/bin/reaper-controller/)

• New overlay_reconciler.rs: watches ReaperOverlay objects, manages finalizer for cleanup, handles reset via generation counter, discovers and calls agents
• Modified reconciler.rs: PVC-like blocking — checks for Ready ReaperOverlay before creating Pods
• Modified main.rs: runs both ReaperPod and ReaperOverlay controllers concurrently
• Added reqwest dependency for controller-to-agent HTTP communication

Agent (src/bin/reaper-agent/)

• New overlay_api.rs: list_overlays(), get_overlay(), delete_overlay() functions
• New HTTP routes: GET /api/v1/overlays, GET/DELETE /api/v1/overlays/{namespace}/{name}
• Public wrappers in overlay_gc.rs for reusing existing cleanup logic

Helm & RBAC

• Controller RBAC updated with reaperoverlays and reaperoverlays/status permissions
• Static manifest (deploy/kubernetes/reaper-controller.yaml) updated
• CRD generation script updated to produce both CRDs

Usage

# 1. Create overlay (like creating a PVC)
apiVersion: reaper.io/v1alpha1
kind: ReaperOverlay
metadata:
  name: slurm
spec:
  resetPolicy: Manual

---
# 2. Reference it in a ReaperPod (blocks until overlay is Ready)
apiVersion: reaper.io/v1alpha1
kind: ReaperPod
metadata:
  name: install-slurm
spec:
  overlayName: slurm
  command: ["bash", "-c", "apt-get update && apt-get install -y slurm-wlm"]

---
# 3. Reset after corruption
# kubectl patch reaperoverlays slurm --type merge -p '{"spec":{"resetGeneration":1}}'

Related

• Closes No mechanism to reset/clean overlay namespaces without direct node access #42
• See also chore: migrate CRD API group from reaper.io to reaper.giar.dev #46 (API group migration reaper.io → reaper.giar.dev)

Test plan

• cargo clippy --workspace --all-targets -- -D warnings passes
• cargo clippy --target x86_64-unknown-linux-gnu --all-targets -- -D warnings passes
• cargo test --workspace — all 163 tests pass
• CRD generation script produces both CRDs correctly
• CI integration tests (Kind cluster: ReaperOverlay lifecycle, PVC-like blocking, reset)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.01%. Comparing base (59ee7c2) to head (187f8cf).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #47   +/-   ##
=======================================
  Coverage   85.01%   85.01%           
=======================================
  Files           6        6           
  Lines         307      307           
=======================================
  Hits          261      261           
  Misses         46       46           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.