5.6 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| what runs on it | accepted | 2026-09-27 | jochen | false | 0102-the-mesh-writes-into-a-shared-file-never-over-it.md |
118. Undeclaring removes what the mesh made, gives back what it changed, and leaves the machine's units as they are
Context
When a resource stops being declared — its module unassigned, the node sent a deliberately-empty declaration (issue 127), or a new catalogue version renaming its id — the host undoes it. The host's own code states the rule it means to follow: it removes what it made and leaves what it merely configured. For almost every resource it does exactly that:
- a container, a network, a process's unit, a directory it created: removed;
- a file it created: removed; a file it replaced: its kept original put back (ADR 0100);
- keys and list members it wrote into a shared file: given back as they were (ADR 0102);
- a package: left installed — the host cannot know it is unused;
- an operator's path it was given access to: never touched (ADR 0051).
A service is the exception. A service resource never installs a unit: it puts one that
already exists — the distribution's, the operator's — into a state. Undeclared, the host stops
it. That contradicts the rule above, and in practice it is the most dangerous thing an
undeclare can do. Found reviewing the uplink modules
(issue 130):
- the private network declares the container runtime's unit only so a change to the registry trust reloads it — unassigning the private network stops the runtime, and every container on the machine, the mesh's and not;
- the sshd module declares the ssh daemon — unassigning it stops ssh, the lockout that module's
own
listensrule forbids; - the uplink modules would have stopped the network manager, taking the machine off the only link the mesh reaches it by.
ADR 0117 (in review) answered that for its own modules with a
service declared with no state. Every other module that declares a unit it did not make is
exposed in the same way, and relying on each author to remember an opt-out is how the next one
is missed.
Considered Options
1. Undeclaring touches nothing on the machine. Rejected. What the mesh made would outlive the module that made it: a container nobody manages keeps serving and stops being patched; a unit the mesh wrote keeps running a bundle nothing updates; a name collides when the module is assigned again. An undeclare that leaves the mesh's own work behind is an orphan factory.
2. Keep stopping services; make "leave it running" an opt-in per resource. Rejected. It keeps the dangerous behaviour as the default for exactly the units that matter most — the runtime, the ssh daemon, the network — and each new module is one forgotten field away from a machine that goes dark when it is unassigned.
3. The line is ownership. Chosen.
Decision
Undeclaring removes what the mesh made, gives back what it changed, and leaves what was the
machine's as it is. For a unit, that means: the host never stops, starts, disables or
enables a unit it did not create when that unit stops being declared. An undeclared service
is forgotten — reported as such — and the unit keeps whatever state it is in.
- A unit the mesh did create — a
processresource's unit, which the host writes — is still stopped and removed with it. That is the mesh's own code. - The service's settings the mesh wrote are given back by their own resources (a kept original restored, a region or keys removed). A running service keeps running on what it read until it next reads its configuration; the mesh does not restart it to make it notice.
- A service declared with no
state(ADR 0117) remains the way to say the mesh must not start a unit either; this record is about what happens when a declaration goes away, and covers every service. - An operator who wants a unit stopped when its module goes says so first: declare it
stopped, push, then unassign. Stopping a machine's unit is a decision, made visibly — never a side effect of removing a module.
Consequences
- Unassigning the private network no longer stops the container runtime; unassigning sshd no longer stops ssh; no uplink module can take a machine's network down on its way out.
- The host's removal report says "forgotten; the unit is the machine's" where it used to say "stopped". A module that relied on its daemon stopping when unassigned — none in the catalogue today does on purpose — needs the explicit step above.
- A daemon can keep running after its module is gone, on configuration that was taken back from under it. That is a visible, running process the operator can see and stop; the alternative was an invisible outage.
- Not decided here: an unassign preview that lists what an undeclare will remove and what it will leave running. Issue 130 asks for it; it is the controller's to build.