Adoption mode: a node in use is adopted before it is converged (hq ADR 0100–0103) #44

2026-09-22T17:28:25Z

jschoubben commented

2026-09-22 17:28:25 +00:00

Implements adoption mode for the controller, per hq ADRs 0100, 0102 and 0103.

Merge after mesh-host and before mesh-catalog. Hosts must understand adoption, opening, into and reload-on before this sends them. The catalogue's new guards field needs this controller's strict manifest parser.

What it does:

A node is adopted or converged, with its taken modules recorded in migrations 0029 and 0030. The mode is set with node add --adopted or token issue --adopted. The latter is refused for an existing converged node, which is pointed to adopt.
Declarations. Every declaration is built by one marshaller. An adopted node's body carries adoption, taken and untaken, where untaken covers every resource kind. A converged node's body and digest are byte-identical to before.
An adopted node's declaration, in place of the filter:
- openings, each from where the filter would admit it;
- a refusal-only guard, derived from the taken modules' ports published to the private network only, plus the store and management ports. It matches only traffic addressed to this machine, is reloaded rather than restarted, and brings its own nftables package.
The host's report is stored: what it holds, the firewall it found, and what is reachable.
The acts: take <node> <module>, converge <node> and adopt <node>, on the CLI and the API.
- Converging refuses while a found container is held.
- The preview names every reachable port with its fate, including ssh and narrowing to the private network, every held thing the flip replaces, and a note that routed traffic is not previewed.
- --yes must carry the preview's digest, and is refused if the host's report is older than 15 minutes.
The foundation's ports are node settings (ports). They are followed by the containers, the filter, the openings, the guard and consumers. They are validated against ssh, collisions and other assignments.
Per-node advisory holds run from compose to send. They are bounded and pin no connection while waiting.
Networking (ADR 0102). It writes the registry's trust into the runtime's file (into: json) and reloads the runtime (reload-on, prefixed like restart-on) instead of restarting it.

Tests: go build ./... && go vet ./... && go test ./... all pass against a throwaway Postgres. The adoption lab bed passed 18 of 19 checks; see the mesh-host pull request. Three independent reviews were done, and every finding is fixed.

Implements adoption mode for the controller, per hq ADRs 0100, 0102 and 0103. **Merge after mesh-host and before mesh-catalog.** Hosts must understand `adoption`, `opening`, `into` and `reload-on` before this sends them. The catalogue's new `guards` field needs this controller's strict manifest parser. What it does: - **A node is adopted or converged,** with its taken modules recorded in migrations 0029 and 0030. The mode is set with `node add --adopted` or `token issue --adopted`. The latter is refused for an existing converged node, which is pointed to `adopt`. - **Declarations.** Every declaration is built by one marshaller. An adopted node's body carries `adoption`, taken and untaken, where untaken covers every resource kind. A converged node's body and digest are byte-identical to before. - **An adopted node's declaration,** in place of the filter: - **openings,** each from where the filter would admit it; - **a refusal-only guard,** derived from the taken modules' ports published to the private network only, plus the store and management ports. It matches only traffic addressed to this machine, is reloaded rather than restarted, and brings its own nftables package. - **The host's report is stored:** what it holds, the firewall it found, and what is reachable. - **The acts:** `take <node> <module>`, `converge <node>` and `adopt <node>`, on the CLI and the API. - Converging refuses while a found container is held. - The preview names every reachable port with its fate, including ssh and narrowing to the private network, every held thing the flip replaces, and a note that routed traffic is not previewed. - `--yes` must carry the preview's digest, and is refused if the host's report is older than 15 minutes. - **The foundation's ports are node settings (`ports`).** They are followed by the containers, the filter, the openings, the guard and consumers. They are validated against ssh, collisions and other assignments. - **Per-node advisory holds** run from compose to send. They are bounded and pin no connection while waiting. - **Networking (ADR 0102).** It writes the registry's trust into the runtime's file (`into: json`) and reloads the runtime (`reload-on`, prefixed like `restart-on`) instead of restarting it. Tests: `go build ./... && go vet ./... && go test ./...` all pass against a throwaway Postgres. The adoption lab bed passed 18 of 19 checks; see the mesh-host pull request. Three independent reviews were done, and every finding is fixed.

jschoubben added 24 commits 2026-09-22 17:28:25 +00:00

Record whether a node is adopted and which modules were taken on it (hq ADR 0100) 1c32af6a22

Carry an adopted node's mode and taken modules in every declaration, from one marshaller (hq ADR 0100) a86a6c2974

Declare openings and a refusal-only guard on an adopted node in place of the filter (hq ADR 0100) c3b1617693

Keep what an adopted node reports holding, the firewall it found and what is reachable on it (hq ADR 0100) 28894fa5bd

Take a module, converge a node after a preview, and return it to adopted, from the command line and the API (hq ADR 0100) 1ea84f8b8f

Read the foundation's ports from each node's settings, wherever a port is used (hq ADR 0100) dbf62b5212

Hold the catalogue's store, broker and filter manifests to what adoption needs of them (hq ADR 0100) c93128d82f

Write the registry's trust into the runtime's file and reload the runtime instead of restarting it; prefix reload-on like restart-on (hq ADR 0102) 28b7fb81ba

Derive the guard from taken modules only: their published private-network ports and their manifests' guards (hq ADR 0103) 8db66e9532

Leave an IPv6 loopback mapping out of what a container publishes, reading ports from the end (hq ADR 0100) a82bfb41f2

Guard only packets addressed to this machine, and order the guard's unit before the network and against shutdown (hq ADR 0103) a2dfaaf4d1