egress-proxies-operator/docs/plans/2026-08-08-1335-lean-scaffold-cleanup.md

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 §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 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

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).