egress-proxies-operator/docs/plans-executions/2026-09-16-0841-provider-blueprint.md

Execution: provider blueprint

Plan: docs/plans/2026-09-16-0841-provider-blueprint.md

• Step 0 — Save the plan; wait for the merge
• Step 1 — Collect evidence (read-only, in parallel)
• Step 2 — Write docs/providers.md
• Step 3 — Verify, then open the MR

Step 0 — Save the plan; wait for the merge

The plan was committed on feat/provider-health (80b2e9c) and reached main through PR #6. After the user confirmed the merge, the branch was cut from the updated main:

git switch main && git pull --ff-only
git switch -c feat/provider-blueprint

Worth noting: .claude/settings.json has local, uncommitted permission edits that carried over through the switch. They are deliberately left out of this branch.

Step 1 — Collect evidence (read-only, in parallel)

Three Explore agents answered the plan's 12-item questionnaire, one each for kubernetes, gcp and kvm. Meanwhile I read the shared layer: internal/provider/*.go, registry.go, the provider wiring in cmd/main.go, reconcileManaged/replaceInstance/reconcileDelete in the controller, internal/gc/gc.go, and how the monitor uses Checker.

Before relying on the agents' claims, I spot-checked them against the code. One was wrong and did not go into the doc: the kvm agent said Delete skips volume removal when DomainDestroy returns ErrNoDomain. In fact removeDomain returns nil there, and Delete still calls removeVolumes afterwards (kvm.go:477-482).

Rules that exist only in the callers, and not in any comment, were found by reading the controller and GC. They went into the doc as MUST rules:

• A zero CreatedAt makes an instance immediately collectable (gc.go:120).
• Get returning ErrPermanent on the deletion path makes the reconciler call Delete anyway.
• Replacement waits for Get to return NotFound before creating an instance with the same name.
• Stopped and Terminated both lead to delete-and-recreate.

Worth noting, found outside this plan's scope and not changed here:

• docs/gcp-vm-validation.md filters on labels.proxy-operator-managed=yes, but the value is true.
• According to the gcp agent, docs/gcp-in-specific-project.md holds a real project ID, IAM output and an egress IP. The user was told.

Step 2 — Write docs/providers.md

Wrote the eight sections the plan lists. Linked the new doc from the Provider contract row in docs/architecture.md and from the CLAUDE.md "Architecture" section.

Judgment calls:

• The file:line evidence sits in per-provider notes under the matrix, as planned. The contract rules in §2 cite the reconciler and GC lines each rule protects.
• The gap list includes documentation drift (kvm-provider.md's ARP order and "from startup" dial, gcp-vm-validation.md's label value and its claim that async errors reach status), as well as code gaps. Both would mislead the next provider author in the same way.
• "Proposed features" stays a flat list with no design, as the user decided.

Worth noting: the line numbers in the doc are a snapshot. The doc says so and asks readers to look for the named function when a line has moved.