Skip to content

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-stack skill 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 acropenmined image 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 main images from acropenmined. 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 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.