terdut-operator/ROADMAP.md

terdut-operator build roadmap

This is the staging plan for implementing the operator against DESIGN.md's settled decisions. It exists for the same reason DESIGN.md and SERVICE-ACCOUNTS.md do: so each stage starts from an agreed sequencing instead of re-litigating "what do we build first" mid-PR.

Sequencing call this roadmap makes

TerdutServer does not take over Deployment/Service/bootstrap (§4.1, §10) until Stage 5. Every earlier stage targets a terdut-server deployed by hand, via the existing charts/terdut-server chart, into a namespace dedicated to this work — disposable, no risk to anything else, and explicitly not something this roadmap plans to migrate in place. This is a green-field build: there's no existing install this operator is on the hook to preserve, so the hand-deployed instance from Stage 1 is meant to be retired once Stage 5's operator-managed instance is proven, not migrated.

TerdutTeam.spec.serverRef still needs a real TerdutServer object to resolve against from Stage 1 onward, though (§4.2, §6) — so TerdutServer shows up early, just with a deliberately narrow first spec covering only what §6's bootstrap/credential flow needs. image/replicas/database land in Stage 5, not before.

Stage 0 — Scaffolding & CI

• go.mod (git.ryuvia.com/niklas/terdut-operator) + Kubebuilder v4 scaffold (cmd/main.go, config/, Makefile, PROJECT), matching terdut-server's Go toolchain and house style (§3). Kubebuilder's own scaffolded Makefile already wires manifests/generate (controller-gen) and setup-envtest into test, and golangci-lint into lint, all fetched on demand into bin/ — no separate install step needed beyond what make test/make lint already do.
• .release.conf deliberately not added yet: it names a HELM_CHART this repo doesn't have until Stage 6. Adding it now would either be a stub that lies about what's releasable or dead config nobody can run — it lands in Stage 6, alongside the chart it describes.
• Gitea Actions CI calling fmt lint test, mirroring terdut-server's ci.yaml convention (its CLAUDE.md: "a green gate here and a green pipeline are the same code, not two descriptions of it") minus the chart/security jobs, which need a chart (Stage 6) and real controller code (Stage 1+) respectively to have anything to check.
• Drop kubebuilder's default .github/workflows/* scaffold — this org runs on Gitea, not GitHub; .gitea/workflows/ci.yaml is the only CI this repo has.
• Housekeeping: drop the stray .DESIGN.md.swp (leftover vim swapfile, shouldn't be committed); correct DESIGN.md §6/§13's "v1-blocking, not v1-shippable" language — the service-account feature it was blocking on has since shipped in terdut-server.

Done when: CI is green on an otherwise-empty scaffold.

Stage 1 — TerdutServer, bootstrap/credentials only

• Deploy terdut-server via its existing chart into a fresh, disposable namespace — manual, out-of-band, nothing operator-managed yet. This chart run bootstraps the server itself, before the TerdutServer CR exists.
• TerdutServer CRD narrowed to spec.endpoint + spec.credentialsSecretRef
  • spec.allowedTeams; the rest of §4.1's spec (image, replicas, networking, database) waits for Stage 5.
• Controller implements §6's bring-your-own path only: spec.credentialsSecretRef set and the Secret exists → adopt it, status.credentialsSecretRef mirrors it, Bootstrapped/Ready: True. Unset (or not found yet) → Ready: False, requeue, no API call made. Self-registration (the /api/bootstrap-race fallback in §6 point 1) is explicitly deferred to Stage 5, not implemented here: Stage 1's own setup never exercises it (the chart always bootstraps first, per above), and this narrowed spec has no username/email fields for it to call /api/bootstrap with in the first place. Adding it later is additive, not a breaking change to this stage's shape.
• No Deployment/Service reconciliation at all in this stage.
• First envtest suite (controller-runtime's fake API server) plus an httptest.Server fake of terdut-server's bootstrap/service-account endpoints, per §11.

Stage 2 — TerdutTeam

• §4.2: serverRef resolution, real update-in-place (POST create / PUT rename / PUT oidc-groups), team-scoped service-account minting once Ready (§6 point 3), finalizer that DELETEs the team server-side and its credential Secret.
• First place the "every child resolves its own teamRef → TerdutTeam.status, never chains up to TerdutServer" pattern (§5) gets proven end to end.

Stage 3 — TerdutEscalationRule + TerdutDeadmanSwitch

• Built together: both stay same-namespace-as-their-TerdutTeam (§1), so neither exercises cross-namespace complexity, but together they cover the two different reconciliation shapes §5's table calls out — whole-policy PUT-on-drift for the escalation policy, delete-and-recreate (no PUT available) for the dead man's switch — against the same shared create/finalizer/resync scaffolding Stage 2 already built.

Stage 4 — TerdutAlertSource

• Last of the children on purpose: it has the subtlest failure mode of the four. Covers webhook Secret generation/ownership (§4.5, §7), the WebhookSecretLost fail-closed condition + Warning event (§5, added 2026-09-30), and the kind-change delete-and-recreate rotation path — all easier to get right with the other three controllers' patterns already in place to build on.

Stage 5 — TerdutServer absorbs Deployment/Service/bootstrap (§10, executed)

• Extend TerdutServer to the full §4.1 spec and stand up a second, operator-managed terdut-server in the same dev namespace — not an in-place takeover of Stage 1's hand-deployed instance. Once this is solid, that hand-deployed instance is simply retired.
• Postgres integration (§8): bring-your-own DSN path first (no external CRD dependency); Zalando postgres-operator path as a follow-up — split into its own stage if it turns out bigger than expected once started.
• This is where §10's "the chart becomes an installer chart" recommendation actually gets executed, rather than just recommended.

Stage 6 — Installer chart + real release

• Package CRDs + the operator's own Deployment/RBAC into the installer chart §10 describes; wire .release.conf/release-vars the same way terdut-server does; run it through the release skill for a real first cut.
• Full kind end-to-end test per §11: create TerdutServer → TerdutTeam → one of each child kind → verify via terdut-server's own API that each object exists with the right shape → delete the CR → verify the server-side object is gone.

Deferred (§13, unchanged by this roadmap)

Cross-namespace allowedTeams exercised against a real second namespace, CloudNativePG support, narrower-than-namespace Secret RBAC for the webhook Secret, gitops-managed team membership, automatic Deployment restart on upstream Postgres credential rotation, admission webhooks/CEL-only validation limits, OLM packaging.