ADR-0010: Preview supply chain — registry topology and image lifecycle
Date: 2026-08-13 Status: accepted Decider: Platform owner (bitsofsteve)
Context
Preview environments deploy images built from unreviewed pull-request code.
The platform registry acropenmined feeds automatic dev promotion: Kargo
warehouses subscribe to exact repositories in it and promote matching tags
with no human step. Preview artifacts must be structurally unreachable by
every promotion watcher.
Source inspection (2026-08-13) proved every promotion consumer binds the registry by exact string: warehouse subscriptions, stage bindings, the pin scripts, and control drift. Nothing enumerates registries. A separately named registry is therefore invisible to promotion by construction.
This decision is routed by the preview-environments program:
PVW-D01 through work package
PVW-M0-W01.
The owner decided DECIDE PVW-D01: OPTION A on 2026-08-13.
Decision
Each environment tier gets its own image registry. Dev keeps acropenmined.
Previews get one dedicated registry. Staging and production get their own
registries later; the STP program records those through its own decisions
(STP-D19).
The preview registry:
- Is a new registry on the Basic service tier, admin access disabled, in the default role-assignment mode. In-place tier upgrade is the growth path.
- Lives in its own Terraform stack with an environment root named
preview, which auto-applies on merge like every non-prod root. - Takes pushes only from the dedicated preview build identity (ADR-0006 amendment via PVW-M0-W02). The grant is registry-scoped: safe, because the registry holds nothing except previews.
- Serves pulls to the dev cluster through one standalone kubelet role assignment in the cluster stack, not through the aks module's single registry input.
The preview image lifecycle:
- Tags use
pr-<N>-<shortsha>. They can never match the promotion tag rule. The registry split makes this a second, redundant barrier. - Deployment references pin digests, not tags.
- Teardown deletes the pull request's artifacts on close or merge.
- A scheduled purge task sweeps stray artifacts after 7 days and build-cache repositories after 14 days. A plain registry-delete CI job is the fallback while the purge tool carries a preview label.
- Builds use registry-backed layer caching so a pull request rebuilds only what changed.
Options considered
Option A — dedicated preview registry, Basic tier, scheduled purge
- Benefit: promotion isolation by construction; no permission machinery; about $5 per month base, $7–12 expected with storage.
- Cost or risk: preview-labeled purge tooling; one more registry to operate.
- Rollback or migration effect: delete the registry; nothing else references it by design.
Option B — dedicated preview registry, Standard tier
- Benefit: 100 GiB included storage; artifact-cache features.
- Cost or risk: $20 per month for headroom previews do not need; the Basic tier upgrades in place when pressure appears.
- Rollback or migration effect: same as Option A.
Option C — shared registry with repository-level ABAC conditions
- Benefit: no second registry.
- Cost or risk: contradicts the recorded owner direction; isolation rests on tag-regex convention instead of topology; permission complexity.
- Rollback or migration effect: entangled; artifacts share storage with promotion-watched repositories.
The owner selected Option A.
Consequences
- PVW-M1 creates the registry stack via the
/new-stackskill and applies it before any pull request that references the registry by name (data-source lookups resolve at plan time). - The kubelet pull grant lands as a standalone role assignment in the dev cluster stack, following the existing kargo-controller pattern.
- The preview build identity and its push grant land in the trust root beside the identity (PVW-M0-W02, break-glass apply).
- The runner-job admission constraint currently allowlists only
acropenminedimage prefixes; the preview guardrail work (PVW-M2) must teach it the preview registry for preview namespaces, or preview runner Jobs are denied. - The new identity joins the control-drift expected state when minted.
- Tests: prove no warehouse or promotion source references the preview registry; prove teardown and purge reclaim storage; prove cache hits on a second build of an unchanged layer.
- Remaining risks: purge tooling is preview-labeled (fallback recorded); the registry adds a small standing cost governed by the PVW cost envelope (PVW-D08).
Amendment — 2026-08-24
The direct Preview implementation keeps the accepted registry topology. It changes these image-lifecycle mechanics:
- The tenant workflow keeps a runtime graph and an image-build graph.
- It builds only images whose Docker inputs changed. Engine also builds its benchmark image.
- Unchanged dependencies use reviewed
mainimages fromacropenmined. Each reference includes a full-SHA tag and an immutable digest. - Pull-request images use commit-qualified tags with
imagePullPolicy: Always. The ApplicationSet cannot receive build digests without another mutable state store. Registry isolation still prevents Preview promotion. - A protected hourly sweep preserves artifacts for every open pull request. It deletes inactive tags only after the safety period.
- Builds use GitHub Actions layer caching instead of registry cache tags.
- Preview-specific admission permits only the selected Preview images and reviewed dependency images.
The commit-qualified tag remains mutable inside the Preview registry. This is accepted because Preview artifacts are disposable and cannot enter promotion.
Supersession and rollback
A later accepted ADR can replace this decision, for example if the platform consolidates registries under a mature repository-permission model. Preview history does not need migration: preview artifacts are disposable by definition.
Program links
- Program decision: PVW-D01
- Dependent work packages: PVW-M0-W02, PVW-M1 foundations (registry stack, kubelet grant), PVW-M2 guardrails (admission constraint), and the STP-D19 reconciliation in the STP register.