From f9e129f734e93e28fd44a57cd9d0cc1f3b6ee08a Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 10 Sep 2026 23:34:59 +0200 Subject: [PATCH] =?UTF-8?q?Issue=20040=20=E2=80=94=20the=20only=20descript?= =?UTF-8?q?ion=20of=20how=20a=20mesh=20is=20stood=20up=20is=20a=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There is no installer. The complete account of standing up a mesh is an integration test in the lab, and a fixture may invent what it needs — this one raised a registry no production has and rewrote every image reference through it, concealing both 039 and the fact that a first node outside the lab had no bootstrap path at all. The bed being green said nothing about whether a mesh could be installed. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF --- .../00-report.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 04-ISSUES/040-the-install-procedure-exists-only-as-a-test/00-report.md diff --git a/04-ISSUES/040-the-install-procedure-exists-only-as-a-test/00-report.md b/04-ISSUES/040-the-install-procedure-exists-only-as-a-test/00-report.md new file mode 100644 index 0000000..ee7c02f --- /dev/null +++ b/04-ISSUES/040-the-install-procedure-exists-only-as-a-test/00-report.md @@ -0,0 +1,58 @@ +--- +status: open +opened: 2026-09-10 +located-in: [] +fixed-by: +amended-design: +--- + +# 040 — The only description of how a mesh is stood up is a test + +## Symptom + +There is no installer. The one complete, executable account of how a mesh comes into existence is +an **integration test** in the lab repository: it builds the images, applies the substrate, enrols +every node, places the overlay, seeds the operator's secrets, registers modules, assigns them, +pushes, and waits for convergence. + +Nothing else does this. `packaging/` installs and supervises the **host agent** on one machine. +[`04-lab-installation`](../../03-DESIGN/01-to-be/04-lab-installation.md) covers the **lab's own** +prerequisites — a virtualisation daemon, storage, a pool. Neither installs a mesh, and no design +section describes doing so. + +## Why this matters + +**A test fixture is allowed to invent what it needs, and this one did.** It raised an image +registry that exists in no production, stocked it from a workstation, and rewrote every image +reference in every manifest to point at it. That single convenience concealed at least two separate +faults for as long as the lab has existed: + +- modules naming a tag where a digest is required, never caught because the harness was assigning + the digests ([039](../039-the-lab-registry-was-silently-pinning-unpinned-modules/00-report.md)) +- the bootstrap itself having **no path at all** on a machine that is not the lab: the mesh's own + control-plane image exists in no registry, so nothing could name it, and the fixture's registry + was the only reason that never surfaced + +**So the bed being green said nothing about whether a mesh could be installed.** Both are the same +fault: the procedure and the reality drift, and the drift is invisible precisely because the thing +that would notice is the thing doing the inventing. + +**And a person cannot run it.** The procedure is expressed as assertions in a test runner, in a +repository whose purpose is to raise disposable virtual machines. Somebody standing up a real first +node has no artefact to use — which is why standing one up has been "a person driving the CLI", +the loop [ADR 0010](../../02-DECISIONS/0010-delivery.md) removed everywhere else and left here. + +## Open questions + +- Where should the procedure live so that **the lab uses it rather than reimplementing it**? The + lab must remain able to raise machines and inject faults; what it should not be able to do is + describe installation differently from the thing an operator runs. +- What is the smallest arrangement that makes drift *impossible* rather than merely discouraged — + the bed invoking the installer, or something generating one from the other? A second description + that is merely kept in step is the arrangement that just failed. +- Which parts of what the test does are genuinely lab-only — documentation addresses, names that + resolve nowhere, injected faults — and which are the mesh's own and belong in an installer? The + distinction has never been drawn, and everything landed on the lab side of it by default. +- How is *"the installer is what installed this"* checked afterwards, on a mesh that is already + running? A mesh cannot say how it was raised, so nothing can currently contradict a claim that it + was raised the supported way.