diff --git a/docs/plans/2026-08-08-1335-lean-scaffold-cleanup.md b/docs/plans/2026-08-08-1335-lean-scaffold-cleanup.md new file mode 100644 index 0000000..fa49f86 --- /dev/null +++ b/docs/plans/2026-08-08-1335-lean-scaffold-cleanup.md @@ -0,0 +1,128 @@ +# Plan: Lean-down cleanup — strip non-goal scaffold from the application footprint +**Created:** 2026-08-08 13:35 + +## Context + +The user asked two things: (1) explain why webhook-related pieces existed at all when +the spec ([docs/prompts/__initial-prompt.md](docs/prompts/__initial-prompt.md) §12) +says "do NOT build: admission webhooks, cert-manager wiring", and (2) audit all +completed work (Steps 0–3) for anything extra, so the project starts as lean as +possible before Step 4 (reconciler) begins. + +**The answer to (1), already given in conversation and to be recorded in the +execution log:** `kubebuilder init` unconditionally generates webhook machinery for +every project. At Step 0 the scaffold was deliberately committed untouched as a +reviewable baseline, with only `.github/` stripped; spec §3's "config/ +(scaffold-generated, kept working)" was read as license to keep the rest. That was a +process gap — §12's non-goals deserved an active pruning pass immediately after the +baseline commit, especially for parts that actually *did* something (main.go started +a real webhook server; e2e installed cert-manager). The active parts were already +removed in commit `7700358` after the user noticed; this plan removes what remains. + +**Could `init` have been told to skip it? No — verified against the v4.15.0 binary +(`kubebuilder init --help`), not from memory.** Its full flag surface is +domain/repo/owner/license/multigroup/namespaced/fetch-deps/skip-go-version-check/ +project-version/plugins; nothing subtracts features. Plugins are purely additive +(helm, grafana, deploy-image, autoupdate — no "minimal" plugin), and while webhook +*code* only appears via `create webhook` (never run here), the baseline *plumbing* +(main.go webhook server, commented kustomize blocks, cert-manager in e2e utils, +prometheus/network-policy dirs) is emitted unconditionally so later `create webhook` +runs have anchors. Scaffold-then-prune is the only supported path to a lean +baseline. (`--namespaced` was the one arguably-applicable flag, but it conflicts +with the kubernetes-pod provider's cluster-wide `ListByTag` for orphan GC — +cluster-scoped was correct.) Record this in the execution log so the next project +bootstrap knows to plan a pruning pass at scaffold time. + +**Scope, per the user's explicit direction:** "tooling around the project is cool, i +just want the application code produced to start as lean as possible." So developer +tooling stays untouched — `.golangci.yml`, `.custom-gcl.yml`, `.devcontainer/`, +`AGENTS.md`, Makefile `lint`/`docker-buildx`/`build-installer` targets, and +`.claude/settings.json` are all explicitly KEPT. The cleanup targets only the +application and its deployed footprint: `config/` manifests that `make deploy` +would apply or that exist solely to serve never-to-be-built features. + +**Code-level audit result (part of this task's deliverable, no action needed):** +Steps 1–3's Go code contains nothing beyond spec that isn't a justified, +already-logged deviation (`Instance.UID`/`CreatedAt` for orphan GC, `MaxLeases +*int32`, `HealthCheck default={}`, registry-as-parameter, kubernetes provider +replacing mock per user decision). Trivial extras (`shortName=px`, +`MaxProperties=32` on attributes) are harmless and stay. `metrics_auth_role*.yaml` / +`metrics_reader_role.yaml` are genuinely used by the secure-metrics filter and the +e2e metrics test — they stay. + +## Scope refinements from user review + +- **KEEP `config/prometheus/`** entirely (user: monitoring manifests stay), + including `monitor_tls_patch.yaml` and the commented `#- ../prometheus` enable + line in the default kustomization. +- **KEEP the paired metrics-TLS plumbing** for coherence with the kept prometheus + TLS patch: `config/default/cert_metrics_manager_patch.yaml`, its commented + `[METRICS-WITH-CERTS]` reference, and the *metrics-certs/ServiceMonitor halves* + of the commented replacements block. Removing half of a pair would leave + dangling comment references — mess, not lean. +- **REMOVE `config/network-policy/`** (user: "we do not need any network policies + at the moment"). +- **KEEP all RBAC manifests** (user: "i want to keep manifests relevant to + rbacs") — including the `proxy_admin/editor/viewer` helper ClusterRoles + originally slated for removal. + +## Removals (all in `config/`) + +1. **`config/network-policy/`** (2 files: kustomization.yaml, + allow-metrics-traffic.yaml) + the commented `#- ../network-policy` line and its + `[NETWORK POLICY]` banner in `config/default/kustomization.yaml`. + +2. **`config/default/kustomization.yaml`** — strip the *webhook-only* parts: the + commented `#- ../webhook` and `#- ../certmanager` resource lines with their + banners; the commented `manager_webhook_patch.yaml` patch reference; and the + webhook halves of the commented replacements block (`serving-cert` Certificate + sources targeting Validating/Mutating WebhookConfiguration cainjection, the + conversion-webhook block, and the + `+kubebuilder:scaffold:crdkustomizecainjectionns`/`...name` markers — anchors + only for `kubebuilder create webhook`, which will never run here). The + metrics-certs/ServiceMonitor replacement halves stay (see scope refinements). + +3. **`config/crd/kustomization.yaml`** — strip the two commented `[WEBHOOK]` blocks + (conversion-webhook patches and the `configurations:` reference) and the + `+kubebuilder:scaffold:crdkustomizewebhookpatch` marker. **Keep** the + `+kubebuilder:scaffold:crdkustomizeresource` marker (one line; anchors + `kubebuilder create api`, which could legitimately run again). + +4. **`config/crd/kustomizeconfig.yaml`** — teaches kustomize how to rewrite webhook + conversion service references; only consumer was the commented block in (3). + +`config/rbac/` is untouched: the operator's own role/bindings, the metrics-auth +roles, *and* the `proxy_admin/editor/viewer` helper ClusterRoles all stay per the +user's direction. + +## Execution steps + +1. Save this plan into the repo per CLAUDE.md: `docs/plans/$(date + "+%Y-%m-%d-%H%M")-lean-scaffold-cleanup.md`, committed on its own before the + cleanup work starts. +2. Delete the files listed above (`git rm`); edit the two kustomization.yaml files. +3. Verify: + - `bin/kustomize build config/default` renders cleanly (proves no dangling + references; kustomize is already in `bin/` from the scaffold). + - `bin/kustomize build config/crd` renders cleanly. + - `go build ./... && go vet ./...` and the `-tags=e2e` variants stay clean. + - `make test` stays green. +4. Append an execution-log section to + [docs/plans-executions/2026-08-07-1747-proxy-operator.md](docs/plans-executions/2026-08-07-1747-proxy-operator.md) + covering: the "why webhooks existed" explanation (scaffold origin + the Step 0 + process gap), the audit's clean bill for the Go code, the keep-tooling scope + decision, and the exact removals. +5. Single commit on `feat/proxy-operator` with the plan-file commit preceding it. + +## Verification + +```bash +bin/kustomize build config/default > /dev/null && echo default-ok +bin/kustomize build config/crd > /dev/null && echo crd-ok +go build ./... && go vet ./... +go build -tags=e2e ./... && go vet -tags=e2e ./... +make test +``` + +All must pass with output identical in substance to pre-cleanup (same tests, same +coverage numbers).