57 lines
3 KiB
Markdown
57 lines
3 KiB
Markdown
|
# ADR-006 — Bootstrap Composition Model: Shared Provider + Per-Component Factories
|
||
|
|
|
||
|
|
**Date**: 2026-06-30
|
||
|
|
**Status**: Accepted
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
The vendored `@olsitec/pulumi-docker` `DockerDeployments` class (T02) is **monolithic**: its
|
||
|
|
constructor takes the full provider map + a flat list of all containers and creates them together,
|
||
|
|
with no mechanism for ordering between containers beyond the network. The foundation bootstrap,
|
||
|
|
however, needs **phase gates** (PLAN-002 §2/§5): Vault must be `operator init`'d and unsealed
|
||
|
|
*between* the data-plane and Forgejo consuming its secrets, and Forgejo must be healthy *before*
|
||
|
|
runner registration/handover. Expressing those gates through the monolithic wrapper is awkward
|
||
|
|
(it would create the provider/network multiple times and cannot interleave an imperative init step).
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
The bootstrap creates the **shared `docker.Provider` and `foundation-net` once** (`bootstrap/lib/context.ts`,
|
||
|
|
`bootstrap/components/network.ts`), and each service is a **pure factory** in
|
||
|
|
`bootstrap/components/<svc>.ts` with signature `(ctx: DeployCtx) => <outputs>` that creates its own
|
||
|
|
`docker.Container`(s) against the shared provider/network. `bootstrap/index.ts` is the single
|
||
|
|
composition point; **phase gates are Pulumi `dependsOn` edges**, not imperative sequencing, so
|
||
|
|
`pulumi up` derives the order.
|
||
|
|
|
||
|
|
The vendored `DockerDeployments` is **retained** as the published `@olsitec/pulumi-docker` API for
|
||
|
|
simple *downstream* (Layer-1) use — deploying a flat list of containers — but the egg does **not**
|
||
|
|
route its phased bootstrap through it.
|
||
|
|
|
||
|
|
Validation override: `FOUNDATION_DOCKER_HOST=ssh://user@host` points the provider at a dev Docker
|
||
|
|
host without editing committed config; `FOUNDATION_ALLOW_UNPINNED=1` lets `VERSIONS` PIN_DIGEST
|
||
|
|
placeholders fall back to tags for local validation only.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
**Easier**:
|
||
|
|
- Phase gates (Vault init, Forgejo-before-handover) are natural dependency edges.
|
||
|
|
- One file per service, each independently ownable by a Wave-2+ agent (clean parallelism).
|
||
|
|
- Validated end-to-end: `pulumi up` over Docker-over-SSH created `foundation-net` on crunchy01
|
||
|
|
(172.30.0.0/24, attachable) and `destroy` removed it cleanly (2026-06-30).
|
||
|
|
|
||
|
|
**Harder**:
|
||
|
|
- More explicit plumbing than the one-call wrapper (a shared `ctx` threaded through factories).
|
||
|
|
- Two composition styles coexist (egg = direct; downstream = `DockerDeployments`) — documented here
|
||
|
|
to avoid confusion.
|
||
|
|
|
||
|
|
## Alternatives Considered
|
||
|
|
|
||
|
|
- **Route the whole bootstrap through `DockerDeployments`**: rejected — cannot express phase gates
|
||
|
|
or the imperative Vault-init step without recreating the provider/network per call.
|
||
|
|
- **Modify the vendored module to support phases**: rejected — it must stay a faithful Stage-1 vendor
|
||
|
|
(ADR-005) and remain useful as the simple downstream API; forking its behaviour now splits it.
|
||
|
|
|
||
|
|
## Confidence
|
||
|
|
|
||
|
|
**High** — the model is implemented and the Docker-over-SSH path is proven against a real x86_64
|
||
|
|
host (crunchy01). Companion: CONTRACT_003, PLAN-002 §5.
|