delivery arc: dependency-ledger appendix (GitHub / Azure Key Vault / zot - blurbs + failure modes)

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.