diff --git a/content/appendix-dependency-ledger.md b/content/appendix-dependency-ledger.md new file mode 100644 index 0000000..a0445b0 --- /dev/null +++ b/content/appendix-dependency-ledger.md @@ -0,0 +1,79 @@ +# Appendix - The dependency ledger: GitHub, Azure Key Vault, zot + +**Series position:** appendix to the delivery arc (VI-VIII) - sits after Course VIII, +beside the phrasebook. DOM-only page: a ledger, not a set-piece - no hero, no scrub +(art optional later; the arc's three scenes carry the visuals). +**Safety gate:** public site - technologies only, zero employer/industry framing. +Claims source from [[zot-registry]], [[homelab-pull-through-registry]], +[[eso-infisical-secrets]] (pattern generalised to the AKV example), [[argocd-stacks]], +public GitHub/Azure/zot docs. + +## Title (thesis) +**Every toolchain stands on services it does not run.** + +## Hook - the uncomfortable default +The delivery arc reads like a closed machine: repo to reconciler to registry to node. +It is not closed. Three of its load-bearing pieces live outside the cluster - one of +them outside the building entirely - and the honest move is to write that down. A +dependency you have not written down is a dependency you will rediscover during an +outage. + +## The ledger +Three columns of truth per dependency: what it is, what leans on it, and - the one +everyone skips - what actually happens when it is down. + +### GitHub - where the desired state lives +A hosted git service; here it is the system of record the whole loop watches. ArgoCD +holds a read-only deploy key and polls a repo + path + revision (Course VI); every +change to the cluster is a commit here first, and the audit trail is the commit log. +LEANS ON IT: ArgoCD sync, rollback (git revert), change review, the "who merged this" +answer. +WHEN IT IS DOWN: the cluster does not care. The reconciler keeps enforcing the last +synced state indefinitely - workloads run, drift is still corrected from cache. What +stops is CHANGE: nothing new can land, and rollback-via-revert waits with it. GitOps +degrades to read-only, which is the graceful half of the design. + +### Azure Key Vault - where the secret values live +A managed secret store; here it is the vault half of the split from Course VI: git +carries the ExternalSecret REFERENCE (a logical name), the vault carries the VALUE, +and an operator inside the cluster exchanges one for the other and keeps it synced. +Rotation happens here, never as a commit. +LEANS ON IT: External Secrets sync, secret rotation, first deploy of anything that +needs a credential. +WHEN IT IS DOWN: already-synced Secrets keep working - the values are materialised +in-cluster, so running workloads feel nothing. What stops is rotation and NEW secrets: +a fresh app blocks at its ExternalSecret, and an expiring credential becomes a real +deadline. Down is survivable; down during a rotation window is an incident. + +### zot - where the fleet pulls from +A self-hosted OCI registry running as a pull-through mirror (Course VII): the fleet +asks zot, zot asks the upstream managed registry (ACR in the arc's example) once, and +every later pull is local. It is the availability seam between the cluster and the +internet - and the control point where what enters the estate can be gated and audited. +LEANS ON IT: every image pull on every node - boot, reschedule, scale-up, node +recovery. +WHEN IT IS DOWN: the sharpest edge of the three. Upstream down + mirror up = nobody +notices, cache serves (that is the mirror's whole argument). Mirror down = nodes fall +back to upstream only if the pull-path config says they may - a disconnected or +mirror-only fleet CANNOT PULL, so running pods keep running but nothing new schedules +and a rebooting node may not come back whole. The mirror is the dependency the other +two get to lean on. + +## Close +Write the ledger for your own stack and notice the asymmetry it exposes: none of these +outages stop what is already running - they stop CHANGE, ROTATION and RECOVERY, in that +order of pain. Design for the outage you will actually have: cache what you pull, split +references from values, and let the cluster hold its last known truth without asking +anyone's permission. + +## Legend terms (DOM layer -> phrasebook additions) +system of record / deploy key / read-only degradation / ExternalSecret / reference vs +value / rotation window / pull-through cache / availability seam / mirror-only pull path + +## Page shape (build note) +Ledger layout, not prose: three cards (or one three-row table on wide viewports), each +carrying the blurb + "leans on it" + "when it is down" strips - the amber FIELD-NOTE +treatment fits the "when it is down" strip. Cross-link each card to its owning course +(VI, VI, VII respectively). No slice scene; if art is ever wanted, a single small +still of three unconnected objects (crystal slab / vault cube / way-station) reusing +the arc heroes' silhouettes - do not generate anything new for this page now.