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