jschoubben
e4327a3a5e
Ordering needed no change for the third time running — resources apply in the order declared and nothing sorts them — and is now asserted, because sorting them for any sensible reason would have passed every other test. Separates ordering from readiness, which the task had run together: a container started is not a container ready. Nothing waits, and what needs something usable retries. That is deliberate and more robust than start ordering, since a dependency can restart long after apply. The network was the first thing in Phase 1 that genuinely needed building, and the first that needed a decision: 0029 records why a shape rather than an action, and the vocabulary is nine.
113 lines
6.0 KiB
Markdown
113 lines
6.0 KiB
Markdown
---
|
|
topic: the tiers
|
|
status: accepted
|
|
date: 2026-08-31
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 02-DECISIONS/0005-the-node-host.md
|
|
---
|
|
|
|
# 29. A network is a shape, because an action cannot be undone
|
|
|
|
## Context
|
|
|
|
**A module of several containers has no way to let them reach each other by name.** A container
|
|
declaration carries a `network` field, and it only ever *joins* one that already exists — it was
|
|
added so the control plane could reach the store and the broker on the machine it was raised on.
|
|
Nothing in the vocabulary **creates** a network.
|
|
|
|
Without one, containers on a machine share the runtime's default bridge, which gives addresses and
|
|
no name resolution between them. So a module that is several containers can only be written by
|
|
publishing ports onto the machine and pointing its own parts at the host — which puts a module's
|
|
private wiring on the machine's own address space, where anything else on the machine can reach it
|
|
and any other module can collide with it.
|
|
|
|
**This is the gap a mail system meets and nothing else so far does**
|
|
([`00-work-breakdown.md`](../03-DESIGN/01-to-be/00-work-breakdown.md) 3.3). It is being taken now
|
|
rather than then, because 3.3 is the task most likely to send work back into the declaration
|
|
language and the least useful place to discover it.
|
|
|
|
**Adding a shape is not a small change, and the host says so** — the vocabulary is asserted
|
|
against a stated number, with the reason written into the failure: *every addition widens what a
|
|
compromised control plane can express, so a change here is a decision.* The host applies what it
|
|
is told; the only bound on a hostile control plane is what the language can say
|
|
([ADR 0004](0004-a-node-and-how-it-joins.md)).
|
|
|
|
## Considered Options
|
|
|
|
1. **An `action` that creates the network.** The vocabulary already has one, the bundle already
|
|
uses seven of them, and `docker network create` with a `verify` is exactly the shape an action
|
|
takes. Nothing would need adding. **Rejected**, on removal:
|
|
|
|
> An action has no footprint the host can undo — it ran, and whatever it did belongs to
|
|
> whatever it acted on.
|
|
|
|
A network made this way **leaks when the module is unassigned**, and the mesh cannot tell: the
|
|
record says an action ran, and there is nothing to reverse. Unassigning a module would leave a
|
|
network behind on every machine it was ever on, and the only way to find them would be to go
|
|
and look. *A resource the mesh can create and never clean up is one it should not create.*
|
|
|
|
There is a second reason, and it is the one that generalises: an action is opaque. **The mesh
|
|
cannot tell what an action did**, so a network created by one is not a thing the mesh knows
|
|
about — it cannot be reported, counted, or reasoned about, and a module could not require one.
|
|
|
|
2. **Publish ports on the machine instead.** No new shape, and it works today. **Rejected.** It
|
|
makes a module's internal wiring part of the machine's address space: two modules that each
|
|
want a database on a fixed port collide, and anything else on the machine can reach what was
|
|
meant to be private. It also makes the module's manifest depend on what else is installed,
|
|
which is the thing provisioning exists to remove.
|
|
|
|
3. **`network` as a ninth shape.** **Adopted.**
|
|
|
|
## Decision
|
|
|
|
**`network` joins the vocabulary, and the vocabulary is nine shapes.**
|
|
|
|
```
|
|
{"id": "internal", "type": "network", "name": "mail"}
|
|
```
|
|
|
|
**A name and nothing else.** Not a driver, a subnet, an address range or a gateway: every one of
|
|
those is a thing a module would have to know about the machine it lands on, and a module that
|
|
names a subnet is a module that collides with whatever else chose the same one. The runtime picks;
|
|
the mesh names.
|
|
|
|
**It is created if absent and removed when no longer declared** — an ordinary shape, with the same
|
|
lifecycle as a directory. That is the whole reason it is a shape.
|
|
|
|
**Declared before the containers that join it.** Resources are applied in the order the module
|
|
wrote them, and orphans are removed in **reverse** — so a network written first is created first
|
|
and removed last, after the containers attached to it are gone. This is not a new rule; it is the
|
|
existing one, and it happens to be exactly right here. A network written *after* its containers
|
|
would fail to remove while they still hold it, and that failure is reported rather than silent.
|
|
|
|
**What it does not do:** it does not reach across machines. A network is one machine's, like
|
|
everything else the host applies. Modules on different machines reach each other over the private
|
|
network the mesh already provides ([ADR 0007](0007-connectivity.md)), and a shape that tried to
|
|
span machines would be a second overlay with a worse contract.
|
|
|
|
## Consequences
|
|
|
|
**The vocabulary is nine, and the count moves with a record.** The test that asserts it names this
|
|
one, so the next person to change it finds the argument rather than a number to edit.
|
|
|
|
**A compromised control plane can now create and destroy networks on a machine.** Stated plainly
|
|
because that is the cost, and the bound is the point: it can create a named network and remove
|
|
one, and it can do neither to anything it did not declare. It cannot inspect, attach to, or
|
|
reroute what is already there — those would be different shapes, and are not being added.
|
|
|
|
**A multi-container module becomes expressible**, which unblocks 3.3 and, less obviously, makes
|
|
several smaller modules simpler: anything that is a service plus a sidecar currently has to
|
|
publish a port to talk to itself.
|
|
|
|
**Nothing is required to use it.** A module of one container declares no network and joins none,
|
|
exactly as now. The substrate keeps using `host`, which is a runtime-provided network and not one
|
|
the mesh creates.
|
|
|
|
## References
|
|
|
|
- [ADR 0005](0005-the-node-host.md) — the host's vocabulary, and why each shape is a decision
|
|
- [ADR 0004](0004-a-node-and-how-it-joins.md) — what may be pushed is bounded by form, not by trust
|
|
- [`03-DESIGN/01-to-be/00-work-breakdown.md`](../03-DESIGN/01-to-be/00-work-breakdown.md) — 1.3,
|
|
and the mail system at 3.3 that this is for
|