42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
# 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](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](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](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](kvm-provider.md),
|
|
[kvm2-provider.md](kvm2-provider.md),
|
|
[gcp-vm-validation.md](gcp-vm-validation.md) and
|
|
[gcp-in-specific-project.md](gcp-in-specific-project.md).
|
|
|
|
Related sections of [architecture.md](architecture.md): the components table,
|
|
[§5 what provider calls do](architecture.md#5-what-provider-calls-do-in-the-outside-world),
|
|
[§10 tracing](architecture.md#10-tracing-internaltracing),
|
|
[§11 provider health checks](architecture.md#11-provider-health-checks-internalproviderhealth)
|
|
and the "Decisions" list. The test layout is in [testing.md](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.
|