egress-proxies-operator/docs/providers.md

Providers

The provider documentation is split into three files so that a new provider can be specified and built from the generic rules alone, without reading how the existing ones happen to work.

• provider-contract.md: what every provider MUST, SHOULD and MAY do, which caller depends on each rule, the behaviour profiles where providers are allowed to differ, the error taxonomy, credential hygiene, testing obligations, the checklist for adding a provider, and the contract's known limits. It never names an existing provider.
• provider-spec-template.md: the questionnaire a new provider's design answers, one entry per decision the contract leaves open. Copy it to docs/<type>-provider-spec.md, fill it in, and hand it to the implementer with the other two files.
• providers-existing.md: how kubernetes, gcp, kvm and kvm2 meet the contract, a table mapping each of them to every profile, their per-provider reference notes, shared gaps and proposed features.

Per-provider user guides: kvm-provider.md, kvm2-provider.md, gcp-vm-validation.md and gcp-in-specific-project.md.

Related sections of architecture.md: the components table, §5 what provider calls do, §10 tracing, §11 provider health checks and the "Decisions" list. The test layout is in testing.md.

Reading order for a new provider

1. The contract, end to end.
2. The template, filled in for the new backend; every unanswered entry is a design decision still to make.
3. The appendix, for a worked example of each profile the spec chose.
4. The user guide of the existing provider closest to the new one.

The single-file blueprint that preceded this split is in the git history of this path.