Adopt the glossary's vocabulary in the mutable design docs
"control plane" -> controller and "substrate" -> foundation throughout 03-DESIGN, 00-META and the README, with 06-the-control-plane.md and 07-the-substrate.md renamed to 06-the-controller.md and 07-the-foundation.md. The immutable 02-DECISIONS records keep their original wording (and links to them are unchanged) — a term retired here may still appear there, which the glossary explains how to read. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
@@ -142,12 +142,12 @@ nox-mesh-host enrol --token <one-time token>
|
||||
|
||||
The token carries **four** things and is carried by a person
|
||||
([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)): the broker's
|
||||
address, the fingerprint to expect, **the control plane's signing identity**, and the right to
|
||||
address, the fingerprint to expect, **the controller's signing identity**, and the right to
|
||||
join once.
|
||||
|
||||
**The fourth is the one this document listed three of.** A node connects to the broker and takes
|
||||
instruction from the control plane behind it, and those are two different identities. Pinning only
|
||||
the broker would make the control plane's authority *transitive* — a compromised broker could then
|
||||
instruction from the controller behind it, and those are two different identities. Pinning only
|
||||
the broker would make the controller's authority *transitive* — a compromised broker could then
|
||||
forge declarations, which, since the host applies whatever the link delivers, is the whole machine.
|
||||
So the transport is verified once at connect, and **each declaration is verified by its signature,
|
||||
every time**.
|
||||
@@ -158,10 +158,10 @@ What happens, in order:
|
||||
2. it checks the broker's certificate against the pinned fingerprint — *before* sending anything;
|
||||
3. it presents the one-time secret **and its own public key**, which the mesh records;
|
||||
4. it reports its `profile` and `inventory` upward;
|
||||
5. the control plane decides what this machine should be, and sends a declaration;
|
||||
5. the controller decides what this machine should be, and sends a declaration;
|
||||
6. the host applies it, reads back, and reports.
|
||||
|
||||
**Step 4 is the one that is easy to miss and is what makes step 5 possible.** The control plane
|
||||
**Step 4 is the one that is easy to miss and is what makes step 5 possible.** The controller
|
||||
cannot decide what a machine should run without knowing what it *can* run — a graphical session,
|
||||
a container runtime, an architecture. The profile is not a diagnostic; it is the input.
|
||||
|
||||
@@ -209,7 +209,7 @@ channel, not about network reachability.** What it forbids is a listening thing
|
||||
instructions and changes the machine. A node being reachable on the overlay — the whole purpose
|
||||
of the overlay — is untouched by it, and so is a person opening a shell on it.
|
||||
|
||||
The distinction is *who can tell this machine what to be*: only the control plane, only over the
|
||||
The distinction is *who can tell this machine what to be*: only the controller, only over the
|
||||
link the node opened, only in declarations of known shape.
|
||||
|
||||
---
|
||||
@@ -219,18 +219,18 @@ link the node opened, only in declarations of known shape.
|
||||
The same path, with the mesh built in the middle of it.
|
||||
|
||||
```
|
||||
# 1 — raise the substrate and the control plane from the carried bundle
|
||||
# 1 — raise the foundation and the controller from the carried bundle
|
||||
nox-mesh-host reconcile
|
||||
|
||||
# 2 — the control plane now exists, and issues the first token
|
||||
# 2 — the controller now exists, and issues the first token
|
||||
mesh-control token issue
|
||||
|
||||
# 3 — the machine joins the mesh it just raised
|
||||
nox-mesh-host enrol --token <token>
|
||||
```
|
||||
|
||||
Step 1 is the bootstrap from [`07-the-substrate.md`](07-the-substrate.md): a container runtime,
|
||||
then PostgreSQL, then the database, then the schema, then the control plane. It needs no identity
|
||||
Step 1 is the bootstrap from [`07-the-foundation.md`](07-the-foundation.md): a container runtime,
|
||||
then PostgreSQL, then the database, then the schema, then the controller. It needs no identity
|
||||
because nothing is being asked of anyone — the host is applying a declaration it already
|
||||
carries, to the machine it is already on.
|
||||
|
||||
@@ -238,7 +238,7 @@ carries, to the machine it is already on.
|
||||
the bootstrap script never had. Its specialness lasted two commands.
|
||||
|
||||
**And enrolment is exercised on node one.** The path every other node depends on is walked
|
||||
immediately, against a control plane on the same machine, rather than being written and first
|
||||
immediately, against a controller on the same machine, rather than being written and first
|
||||
used months later on node two.
|
||||
|
||||
---
|
||||
@@ -265,7 +265,7 @@ closes — an authoritative local store, reconcile on start, *last heard from* r
|
||||
alarm — is what an episodic host needs, at a shorter period.
|
||||
|
||||
**It cannot be the first node**, and that is not a limitation to work around. Every step of
|
||||
raising a substrate is a `package`, a `container` or an `action` against one, and a partial host
|
||||
raising a foundation is a `package`, a `container` or an `action` against one, and a partial host
|
||||
refuses the first two. So `mesh-host-android bundle` returns a file that says so rather than an
|
||||
empty placeholder waiting to be filled in.
|
||||
|
||||
@@ -350,7 +350,7 @@ rest. The rule that exists to stop the host lying about what it did also makes i
|
||||
|
||||
## Updating what the node holds
|
||||
|
||||
An ordinary declaration. Someone assigns a module; the control plane recomputes what that node
|
||||
An ordinary declaration. Someone assigns a module; the controller recomputes what that node
|
||||
should be and sends it; the host applies the difference and removes what is no longer declared.
|
||||
|
||||
**Removal is not symmetric, and the asymmetry is the design:**
|
||||
@@ -410,7 +410,7 @@ one binary that has always been the same binary.
|
||||
|
||||
Two cases, and they are genuinely different.
|
||||
|
||||
**Graceful.** The control plane sends a final declaration that names nothing. The host removes
|
||||
**Graceful.** The controller sends a final declaration that names nothing. The host removes
|
||||
what it owns by the table above, reports, and drops its identity. The machine keeps the host
|
||||
installed and is back to `hosted`. Nothing is left behind that anybody has to remember.
|
||||
|
||||
@@ -638,7 +638,7 @@ lets a node verify a mesh it has never spoken to
|
||||
([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)). A token emailed,
|
||||
committed, or dropped in shared storage has lost the only property that makes it worth carrying.
|
||||
|
||||
**On the first node it comes from the control plane that was raised two commands ago**, which is
|
||||
**On the first node it comes from the controller that was raised two commands ago**, which is
|
||||
the same command against a mesh that is one machine old.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user