delivery arc VI-VIII: course briefs (GitOps, supply chain, Helm contexts) + NB2 scene prompts 09-11

2026-08-17 12:44:44 +10:00
parent 5cce8c5cd3
commit 7caa9d5342
6 changed files with 391 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Course VII - The image supply chain: registries, mirrors, tags and digests
+
+**Series position:** second course of the delivery arc. Course I taught what an image IS;
+this course teaches how one travels - and how to say its name precisely.
+**Safety gate:** public site - technologies only. Claims source from [[zot-registry]],
+[[homelab-pull-through-registry]], [[work-container-image-tagging]] (generalised: the
+calendar-rev pattern taught as "a human tag scheme", no corp framing), Azure Container
+Registry as the generic managed-registry example, OpenShift IDMS behaviour from public
+Red Hat docs.
+
+## Title (thesis)
+**A tag is a promise. A digest is a fact.**
+
+## Hook - the uncomfortable default
+`myapp:latest` feels like a name. It is not - it is a sticky note. A tag is a mutable
+pointer anyone with push rights can peel off one image and press onto another, and
+nothing anywhere records that it moved. The digest - sha256 of the content - is the
+image's actual name: same bytes, same digest, forever. Most outages in this territory
+begin with two machines both holding "the same tag" and running different code.
+
+## Move 1 - Say the name properly
+Three ways to name an image, in rising order of honesty: `:latest` (a moving target),
+`:1.4.2` (a promise somebody keeps, until they re-push it), `name:1.4.2@sha256:...`
+(a fact - the tag stays for human eyes, the digest does the pulling). Content-addressing
+is the same idea git uses for commits: the name IS the bytes. Pin by digest and "what is
+running?" has exactly one answer.
+Say it like you mean it: **the tag is for reading, the digest is for pulling.**
+FIELD NOTE (amber): `:latest` is how two nodes run different code from one manifest -
+the second node pulled an hour later, after a re-push. Nobody changed the YAML.
+
+## Move 2 - Why a fleet pulls once
+Between the build and the node sits the registry chain. Upstream, a managed registry
+(Azure Container Registry as the worked example) holds what CI built. In front of the
+cluster sits a MIRROR - a pull-through cache like zot: the fleet asks the mirror, the
+mirror asks upstream once, everything after is local. Three reasons this exists: rate
+limits and egress cost (a hundred nodes should not make a hundred internet pulls),
+availability (the fleet boots even when upstream is down or the site is disconnected),
+and control (one place to gate, scan and audit what enters). OpenShift formalises the
+re-route with image mirror rules - and carries a sharp edge: its digest-mirror rules
+rewrite DIGEST pulls only, so a by-tag pull silently skips the mirror. The pinning habit
+from Move 1 is what makes the mirror actually catch the traffic.
+FIELD NOTE: a mirror can also serve a STALE tag->digest mapping while upstream moved the
+tag. Pin by digest and the whole chain becomes content-addressed - the mirror cannot be
+wrong about a hash.
+
+## Move 3 - Build once, promote by copy
+The anti-pattern: rebuild the image for each environment ("the prod build"). Every
+rebuild is a different artefact - different digest, different bytes, untested by the
+stages before it. The discipline: build ONCE, then PROMOTE the same digest through
+environments by copying (skopeo copy, registry to registry) - dev proves the exact bytes
+prod will run. Human-readable tags ride along (a calendar-plus-revision scheme reads well:
+month, year, revision), but the digest is the through-line; promotion never changes it.
+Say it like you mean it: **if the digest changed, it is not a promotion - it is a new
+candidate.**
+
+## Close
+Everything in this course is one idea wearing three coats: names that can move are
+convenient exactly until they move. Address content by what it IS, let humans keep their
+readable labels, and the supply chain stops being a chain of trust and becomes a chain
+of arithmetic.
+
+## Legend terms (DOM layer)
+tag / digest / content-addressing / pull-through mirror / disconnected pull / rate limit /
+image mirror rule (digest-only rewrite) / build-once / promotion / skopeo copy
+
+## Scene concept (hero + slices, the v3 mechanism)
+Exploded left-to-right journey: the layered image CUBE from Course I (familiar - four
+thin slabs, tight formation, reads as one unit now) -> upstream registry TOWER (tall
+managed vault, cool white-cyan) -> the mirror WAY-STATION (squat wide cache block, warm
+cyan, visibly closer to the cluster side) -> the node/cluster CORE. Floating above the
+journey, two seal plates apart from each other: a GHOST RIBBON plate (the tag - faint,
+translucent, edges blurring) and an ENGRAVED SEAL plate (the digest - dense, crisp,
+crystalline). 6 parts, generous void, no connectors. Slice plan: collapse draws the
+journey into the mirror block (everything local); the two seals collapse toward each
+other but never merge - ghost stays ghost.