mesh-bootstrap: the installer, and the two things its first real run found #8
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: novox/mesh-host#8
Reference in New Issue
Block a user
Implements hq ADR 0067. A bare machine given the host binary, this installer, docker and a path to the internet becomes a working mesh — no source, no registry, no toolchain.
The installer
cmd/mesh-bootstrap, a separate program from the host, deliberately:mesh-hoststates that it connects to nothing and listens on nothing, and that claim is what makes the thing running forever on every machine auditable. An installer connects to plenty. Same tier, same delivery, different program.It carries the control-plane image (
make bootstrap IMAGE=…, ~22 MB), so genesis needs no source checkout and no forge — which matters, because the forge runs on the mesh, and needing it to rebuild would mean needing the mesh to rebuild the mesh.Ten steps, every one idempotent: preflight → load → bundle → apply → verify → enrol → registry → publish → control → retire. The temporary control plane is called
temp-mesh-controland the permanent onemesh-control, so they are two containers with two owners and there is nothing to hand over.An image may be named by its own configuration digest
A manifest digest is assigned by a registry on push. The mesh's own control plane is built from source and pushed nowhere, so insisting on one meant a registry had to exist first. A bare
sha256:…is equally immutable and requires nothing to have served it.What the first real run found
Everything before this was injected-runner tests. Running it against a machine found two:
Verified live:
novox is a working mesh of one, bootstrapped through the installer, withmesh-controlrunning from127.0.0.1:5000/mesh-control@sha256:…and the temporary one gone.Steps 6 to 10, which turn a substrate into a mesh that can maintain itself (novox/hq ADR 0067). 6 enrol a node record, a token, `mesh-host enrol`, and the host agent running. Proved by the mesh having HEARD from the node, not by a process existing: a host that cannot reach the broker looks exactly like a successful install until the first push applies nothing. 7 registry the module that gives this mesh an image store, registered from a --catalog checkout, assigned and pushed. Its image is upstream and never built (04-ISSUES/029) — a placeholder digest there is refused. Verified by asking `/v2/`, because a container that is up is not a registry that serves. 8 publish the carried image pushed into that registry, which assigns it the first manifest digest it has ever had. This is the hinge: without it the mesh works and can never upgrade itself. 9 control the control plane registered as an ordinary module pinned to that digest, with the substrate's own store connections delivered through `secret accept` — read out of the bundle that made them, because the mesh cannot invent a credential that predates it. 10 retire the temporary control plane dropped from the bundle and removed by the host's ordinary removal pass. Every step asks before it acts and reports "already done". No step leaves the machine without a control plane: steps 9 and 10 overlap deliberately, and two stateless control planes are untidy rather than broken. mesh-control's `internal/builder`.PublishImage is mirrored rather than imported — tier 0 depends on nothing that must be installed first — with one correction: the digest is chosen from RepoDigests by repository instead of taken as element zero, so an image pushed to two registries cannot silently pin this mesh to the wrong one. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzFThe catalogue's mesh-control manifest landed while this was being written, and it does what the ordinary case does: it keeps its secrets under /var/lib/mesh and mounts them into the container at /run/secrets, so MESH_STORE_INVENTORY_FILE names a path that no own-secret writes. Matching on the path alone found nothing and would have refused a correct manifest. So the lookup follows the volumes. It also reads the other shape the manifest uses — `VAR=${secret:name}` inside the environment file a container reads — which is how a value that is not a path gets in at all, and which is where the broker's two credentials live. That generalises what is delivered: every variable the module fills from a secret is looked up in the substrate's control plane. What the substrate names is accepted through `secret accept`; what it does not is left for the mesh to generate, and said so. A store connection the substrate does not name stays an error — a control plane that cannot open a context is not one. Checked against the real manifest (mesh-catalog feat/control-plane-module): five variables resolve, the placeholder pins in one place, and the container it waits for is `mesh-control`. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzFAn image id does not survive `docker save` -> transfer -> `docker load`. The id is the digest of the image's *configuration*, and a runtime rewrites that configuration as it loads: a newer Docker saves in one format, an older one stores it in another. Same layers, same program, different name. Measured on a live raise: saved on the workstation sha256:b86bb81ca2f9691f24f4725f50962d1e49c98c5ffe211113241243d42d18ceea loaded on the machine sha256:2dc219046c73702fc640317f0342a28ec962ef1e9ef547b2f02861c508ca78fb `internal/image`.ID read the id out of the carried tar and its comment said that was the id the runtime would assign. That is true on the machine the image was built on and false on every machine it is carried to — which is every machine this program exists for. The installer then either stopped at step 2 refusing the runtime's answer, or would have written a bundle naming an image the machine does not hold; and nothing serves an image named by the digest of its own configuration, which is the whole point of naming one that way, so the apply would have died inside a pull that cannot succeed. The lab hit this. So the image is identified by its TAG, which is ordinary metadata the tar carries through unchanged. The runtime is asked what that tag resolves to before the load (already held, nothing to do) and again after (this is what the bundle names). The tag never reaches the bundle — a pinned bundle may not rely on one, ADR 0006 — it is how the id is obtained, not what is written down. - image.ID becomes image.ArchiveID, and says plainly that it is a fact about the file and not a prediction about any machine. It is kept for reports, and printed beside the runtime's answer whenever the two differ. - Idempotence is decided from what the runtime holds under the tag, not from a predicted id, which cannot answer the question at all here. - An untagged archive is refused, in preflight and again at the load: there would be no portable name to ask about, and the only thing left is scraping a sentence `docker load` writes for a person. `make bootstrap` refuses an id or an untagged image, so it is caught in front of whoever can fix it. - A dry run cannot know the id and says so rather than pretending. Run refuses to write a bundle carrying an unconfirmed id at all. Tests: the injected Runner now answers with an id DIFFERING from the tar's, and the runtime's answer is what must be used. The test that refused a differing id encoded the mistake and is replaced by one refusing an answer that is not an id at all. Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF