Compare commits
28
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2b5119ecd2 | ||
|
|
96bdffa9bc | ||
|
|
4eb16f1028 | ||
|
|
d199de40db | ||
|
|
9a1dc4665c | ||
|
|
14be8576f8 | ||
|
|
3c0f7082e6 | ||
|
|
0dd00e88b6 | ||
|
|
eef54917ec | ||
|
|
e9b1010bc0 | ||
|
|
f6ed3545b7 | ||
|
|
0b08cdfce1 | ||
|
|
bffd2af40c | ||
|
|
4a51ea4b3a | ||
|
|
6c14d313b8 | ||
|
|
ced547dae9 | ||
|
|
38482435af | ||
|
|
cf8a8d78c9 | ||
|
|
9de25994e9 | ||
|
|
64ea47b11d | ||
|
|
eba24a72af | ||
|
|
78d4873f4f | ||
|
|
ddfd62edf6 | ||
|
|
f65664640a | ||
|
|
492ac7be18 | ||
|
|
5ac77e3cef | ||
|
|
a619022c35 | ||
|
|
49c065c204 |
@@ -1,6 +1,6 @@
|
||||
---
|
||||
topic: building it
|
||||
status: proposed
|
||||
status: accepted
|
||||
date: 2026-09-01
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
@@ -101,3 +101,19 @@ the digest down after building.
|
||||
**Whether kind 4 deserves a module at all.** Thirty-five descriptions that say *install this and
|
||||
write these files* may be better as one module with settings than as thirty-five modules. Left
|
||||
open deliberately; it is a question about the shape of the catalogue, not about whether to have one.
|
||||
|
||||
## Accepted, 2026-09-29, against what was built
|
||||
|
||||
*Marked in a grooming pass: the mesh was built to this record and the record still said `proposed`.*
|
||||
|
||||
The proposal is the arrangement that exists. `mesh-catalog` holds descriptions of software we did
|
||||
not write and the programs that provision it, and holds neither the mesh's own components nor an
|
||||
application's own module. The mesh's list of modules is a table in the control plane, filled by
|
||||
`module add`, and every module records the source it came from with the commit it was read at.
|
||||
|
||||
**One half is not built: `module check` as a command on the control plane's binary.** A manifest is
|
||||
still validated by a test that reaches into the control plane's internals — which works for this
|
||||
catalogue and gives nothing at all to somebody describing their own application in their own
|
||||
repository, which this record says is the case that matters most. That is
|
||||
[issue 148](../04-ISSUES/148-a-manifest-outside-this-catalogue-has-no-check/00-report.md).
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: proposed
|
||||
status: accepted
|
||||
date: 2026-09-25
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
@@ -275,3 +275,11 @@ On acceptance, each of these is superseded or amended by this record, not edited
|
||||
everything a module needs is a requirement
|
||||
- [Issue 095](../04-ISSUES/095-a-module-assigned-after-genesis-has-no-broker-account/00-report.md),
|
||||
[issue 103](../04-ISSUES/103-a-container-is-not-recreated-when-a-file-it-reads-changes/00-report.md): what fails today
|
||||
|
||||
## Accepted, 2026-09-29, against what was built
|
||||
|
||||
*Marked in a grooming pass.* The vault is a module providing `secret` at mesh scope, and six
|
||||
modules in the catalogue require it — so a shared secret is a requirement answered by the vault,
|
||||
which is what this record asks for. Private keys are still made where they are used and never
|
||||
travel, which is the other half and was never in question.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: proposed
|
||||
status: accepted
|
||||
date: 2026-09-26
|
||||
deciders: jochen
|
||||
extends: 0112-a-module-definition-names-no-node-mesh-or-path.md
|
||||
@@ -47,3 +47,10 @@ other boundary already is: the module name.
|
||||
node runs one of each (ADR 0115)" — instead of failing on whichever name collides first.
|
||||
- Multi-tenant asks are answered in the catalogue (a second module definition), not in the
|
||||
control plane.
|
||||
|
||||
## Accepted, 2026-09-29, against what was built
|
||||
|
||||
*Marked in a grooming pass.* The rule is enforced where it cannot be forgotten: `assignment`'s
|
||||
primary key is `(node, module)`, so a second assignment of one module to one machine is not a thing
|
||||
the mesh can hold. The record read `proposed` while the schema had already settled it.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ extends: 0102-the-mesh-writes-into-a-shared-file-never-over-it.md
|
||||
## Context
|
||||
|
||||
When a resource stops being declared — its module unassigned, the node sent a
|
||||
deliberately-empty declaration ([issue 127](../04-ISSUES/127-a-declaration-that-shrinks-to-empty-is-skipped-not-sent/00-report.md)),
|
||||
deliberately-empty declaration ([issue 149](../04-ISSUES/149-a-declaration-that-shrinks-to-empty-is-skipped-not-sent/00-report.md)),
|
||||
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:
|
||||
|
||||
@@ -99,6 +99,31 @@ composed, so it is not certified.
|
||||
binding. The per-node source override becomes its reach, widened from the filter alone to the names
|
||||
and the certificate as well.
|
||||
|
||||
## Progressive insight — 2026-09-29, from building it
|
||||
|
||||
**Reach does not mean the same thing to the filter for an endpoint the proxy serves.** The decision
|
||||
above says `internal` means "the filter opens the machine port to the private network" and `public`
|
||||
means "the filter opens it to anywhere". For a routed endpoint the second half is wrong, and
|
||||
[ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md) already said so before this
|
||||
record was written: *a public service is exposed through the proxy, not by opening its own port* — it
|
||||
listens `from: mesh`, only the proxy reaches it, and it is exposed by name.
|
||||
|
||||
Found by trying to express one real module, not by review. Its routed name must be public, because
|
||||
browsers post to it; its machine-side port must not be, because that port serves the dashboard in
|
||||
cleartext. Under one value driving both, saying "public" would have reopened a port an operator had
|
||||
just closed. Measured the same evening: that module's routed name answered from the internet over TLS
|
||||
while its machine-side port was refused from the same place. The port is not the path.
|
||||
|
||||
So the reach of a **routed** endpoint asks for names, and its port keeps what the manifest said. The
|
||||
reach of an **unrouted** endpoint — git over ssh, a mail port, the bus — governs the port, because
|
||||
there is no name and the port is the only way in. That is the same split this record already draws in
|
||||
*an endpoint that is not routed is reached but never named*; what it got wrong was carrying the filter
|
||||
across it.
|
||||
|
||||
This corrects a fact, not the decision: one statement per endpoint, three things derived from it and
|
||||
none of them deciding on its own, all stand. The table in the decision should be read with the filter
|
||||
column applying to an unrouted endpoint.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **A manifest gains endpoint names, and a route contribution names an endpoint instead of a port.**
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: superseded
|
||||
date: 2026-09-29
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 02-DECISIONS/0010-delivery.md
|
||||
superseded-by: 02-DECISIONS/0144-anything-on-a-machine-may-call-anything-on-it.md
|
||||
---
|
||||
|
||||
# 143. A consumer verifies the grant it is given
|
||||
|
||||
## Context
|
||||
|
||||
A **grant** is what the mesh writes on a consumer's machine so it can reach a provider. The real one
|
||||
the forge receives for its database, as it arrives:
|
||||
|
||||
```
|
||||
provision postgres-database
|
||||
at <the provider's machine, by name>
|
||||
port the machine port the provider is published on
|
||||
as the role the provider created for this consumer
|
||||
```
|
||||
|
||||
with the credential sealed in a separate file. Four facts and a password, and they are the whole
|
||||
mechanism by which anything in the mesh reaches anything else.
|
||||
|
||||
**The mesh asserts that claim and never finds out whether it is true.**
|
||||
[Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md):
|
||||
converging a machine dropped the path from a container to a port on its own machine, and for eleven
|
||||
hours the mesh answered *all doing what they were told, all heard from, every module current with its
|
||||
source* while a web application logged, six thousand times:
|
||||
|
||||
```
|
||||
connection to server at "<the machine>" (10.10.0.1), port 6852 failed: timeout expired
|
||||
```
|
||||
|
||||
Every check the mesh makes passed, because every check it makes is about the relationship between the
|
||||
mesh and a machine: the declaration was applied, the digest matched, every container named was running.
|
||||
None of them asks whether a consumer can reach what it requires — though the mesh composed the grant
|
||||
and therefore knows the consumer, the machine, the address, the port and the credential.
|
||||
|
||||
**And where the check runs decides whether it catches anything.** The rule in force admitted the
|
||||
machines' own addresses on the private network. A dial from the *machine* to its own address carries
|
||||
exactly such a source address, so a check run by the host on its own behalf would have matched that rule
|
||||
and passed — while every container on the machine was refused. This is inference from the rule that was
|
||||
loaded, not a measurement: the fault was found and fixed before anyone thought to dial from the host.
|
||||
It is enough to decide the question, because a check whose position differs from the consumer's is
|
||||
testing something nobody asked about.
|
||||
|
||||
## Considered Options
|
||||
|
||||
1. **The control plane dials each provision.** Rejected, and it is the tempting one because the control
|
||||
plane holds every fact. It sits on the provider's machine for most provisions here and reaches the
|
||||
address by a path no consumer uses; in the measured outage it would have passed throughout.
|
||||
2. **The host dials on the consumer's behalf, from the machine.** Rejected for the reason above: the
|
||||
machine's network position is not the consumer's, and the one outage this exists to catch is exactly
|
||||
a difference between them.
|
||||
3. **Ask the module.** Rejected: a module is arbitrary software that the mesh does not write. Some could
|
||||
report on their provisions and most cannot, and a check that covers the modules that opted in tells
|
||||
nobody anything about the rest.
|
||||
4. **Read the module's logs.** Rejected: the failure was in a log the whole time, and reading a module's
|
||||
logs makes the mesh depend on the wording of software it does not control.
|
||||
5. **The consumer verifies it, from its own network position.** Adopted.
|
||||
|
||||
## Decision
|
||||
|
||||
**A consumer verifies each grant it is given, from its own network position.** After a reconcile has
|
||||
applied a grant, the machine opens a connection to the address and port that grant names, from inside
|
||||
the consumer's own network namespace — the same position the consumer's software dials from, which is
|
||||
the only position that answers the question the grant asks.
|
||||
|
||||
**It is a connection, not a conversation.** Whether the port accepts a connection is what a grant
|
||||
claims; whether the credential is right, the role exists or the schema is current is the provider's to
|
||||
answer and the consumer's to discover. A check that spoke each provision's protocol would be a second
|
||||
implementation of every provision, and would fail for reasons that are not the mesh's.
|
||||
|
||||
**One failure is not news.** A provider restarting is ordinary, and so is a consumer between containers.
|
||||
A grant is reported unreachable only after it has failed on **consecutive** reconciles, and the count is
|
||||
what the machine reports rather than the last attempt — so a reader can tell "it was briefly away" from
|
||||
"it has never worked".
|
||||
|
||||
**A grant that cannot be checked is said to be unchecked, never assumed good.** A consumer that is not
|
||||
running has no network position to dial from; that is not a broken grant and must not read as one. It is
|
||||
also not a verified grant, and the two are different sentences.
|
||||
|
||||
**What it costs to be wrong is the constraint on all of it.** A check that reports a working provision
|
||||
broken trains a reader to ignore the report, which is worse than having none — the fault this
|
||||
repository keeps finding, one level up. So the threshold is consecutive failures, the check is the
|
||||
cheapest thing that answers the question, and an unknown is reported as unknown.
|
||||
|
||||
**The mesh says it where it says everything else.** A machine's report carries its unreachable grants,
|
||||
and `status` names them beside what is out of date — so "every module current with its source" stops
|
||||
being the whole of what the mesh will tell you about a machine whose modules cannot reach each other.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The mesh can be wrong out loud.** It has been able to assert a grant and not check it; now a grant
|
||||
that does not work is a thing the mesh says, and the eleven hours of issue 145 become minutes.
|
||||
- **The host gains the ability to act from a container's network position**, which it has not needed
|
||||
before. That is a real capability and the only one this needs.
|
||||
- **A machine reports something that is not about the declaration.** Everything it reports today is
|
||||
what it applied and what it holds; this is the first thing it says about whether what it applied
|
||||
works.
|
||||
- **A provision with no port is not checked**, because there is nothing to dial. Several are files and
|
||||
secrets, and saying "checked" about those would be the appearance of verification that this record
|
||||
exists to remove.
|
||||
- **What got harder:** a reconcile does more than apply. Every grant adds a connection attempt on a
|
||||
cadence, which is cheap individually and worth naming: a machine with many consumers dials once per
|
||||
grant per reconcile.
|
||||
|
||||
## How it is checked
|
||||
|
||||
- **The outage is caught.** A bed drops the path from a consumer's network position to a provider's
|
||||
port while leaving the machine's own path to it open — the exact shape of issue 145 — and the grant
|
||||
reads unreachable. This fails against the previous behaviour, where nothing reported anything, and
|
||||
against a check run from the machine, which passes while the consumer cannot reach it.
|
||||
- **A restarting provider is not an outage.** One failed reconcile reports nothing; the count rises and
|
||||
falls, and the grant reads reachable again without anybody acting.
|
||||
- **A consumer that is not running reads unchecked, not broken**, asserted separately from the
|
||||
unreachable case because they are different sentences.
|
||||
- **A provision with no port is not claimed to be checked.**
|
||||
- **The report carries the count, not the last attempt**, so "briefly away" and "never worked" are
|
||||
distinguishable by a reader who sees only the report.
|
||||
- **`status` names an unreachable grant**, asserted on the output, since a check nothing surfaces is
|
||||
the same as no check.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR 0010](0010-delivery.md) — the declaration is owned resources; a grant is one of them
|
||||
- [ADR 0009](0009-modules-and-the-graph.md) — what a provision and a consumer are
|
||||
- [issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
|
||||
— the eleven hours
|
||||
- [issue 136](../04-ISSUES/136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md) — the
|
||||
same distance between a declaration and a machine, one level down
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: accepted
|
||||
date: 2026-09-29
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 02-DECISIONS/0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md
|
||||
supersedes: 02-DECISIONS/0143-a-consumer-verifies-the-grant-it-is-given.md
|
||||
---
|
||||
|
||||
# 144. Anything on a machine may call anything on it, and that is the whole of "local"
|
||||
|
||||
## Context
|
||||
|
||||
Everything in the mesh should be able to call:
|
||||
|
||||
- what runs on the same machine;
|
||||
- another machine's service over the private network, if that service is exposed there;
|
||||
- another machine's service over the public network, if it is exposed there.
|
||||
|
||||
Three cases. The filter had two of them.
|
||||
|
||||
**The first was broken and the break was invisible.** A service exposed to the private network rendered
|
||||
as the machines' own addresses on it. A caller on the machine carries such an address; a caller inside
|
||||
one of that machine's containers carries a bridge address and matched nothing. Measured:
|
||||
|
||||
```
|
||||
the machine: local 10.10.0.1 dev lo src 10.10.0.1
|
||||
a container: 10.10.0.1 via 172.17.0.1 dev eth0 src 172.17.0.8
|
||||
```
|
||||
|
||||
Same destination, same machine, two source addresses. The rule named the first and silently refused the
|
||||
second, so a module reaching its database on its own machine's name timed out for eleven hours
|
||||
([issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)).
|
||||
|
||||
**The second case works, and by accident.** A caller on another machine reaches the private network over
|
||||
the tunnel, and arrives carrying that machine's own address — so the rule matches. It would not have
|
||||
matched the caller's own address either; the tunnel rewrites it. That two of three cases worked is why
|
||||
this looked correct.
|
||||
|
||||
**[ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md) answered the wrong question.** Written
|
||||
hours earlier, it proposed that a consumer verify each grant it is given by opening a connection from
|
||||
its own network position — and it went to some length about *which* position, because whether a caller
|
||||
sat in a container changed the answer. That difference was the bug. A verification mechanism would have
|
||||
reported this outage sooner and would not have prevented it, and the machinery it needed existed only
|
||||
because the rule was wrong. The remedy for a configuration error is the correct configuration.
|
||||
|
||||
**And a module is not a container.** A module is software that delivers one or more services, and it may
|
||||
do that as a container, an installed package with a unit, a binary, or files something else reads. Of 72
|
||||
modules in the catalogue, 61 happen to use a container and 11 do not — among them the resolver, the ssh
|
||||
daemon and the intrusion-prevention module. A rule that reasons about containers describes most of the
|
||||
mesh and not the mesh.
|
||||
|
||||
## Considered Options
|
||||
|
||||
1. **A line per service admitting the machine's own callers.** Rejected: it is what was written first,
|
||||
and it only ever covers the services somebody remembered to think about. It also states, service by
|
||||
service, a thing that is true of the machine.
|
||||
2. **Verify each grant from the consumer's position** ([ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md)).
|
||||
Rejected as a remedy: it observes the fault rather than removing it, and the question it agonised over
|
||||
— which network position — exists only while the fault does.
|
||||
3. **Enumerate the addresses a machine's callers may have.** Rejected for the reason no address is named
|
||||
anywhere in this filter any more ([ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md)):
|
||||
a range describes one machine and goes stale in silence.
|
||||
4. **Local is not filtered, stated once.** Adopted.
|
||||
|
||||
## Decision
|
||||
|
||||
**Anything on a machine may call anything on that machine, and the filter says so once.** Not per
|
||||
service, not per port, and not by naming who the callers are: traffic that did not arrive from outside
|
||||
the machine and did not arrive over the private network is the machine's own, and is admitted. It is
|
||||
asked by the link the traffic arrived on, because that is a fact about the machine rather than a list
|
||||
that describes one.
|
||||
|
||||
**Local is not a boundary this mesh draws.** Whether a caller is a container, a unit, or the operator's
|
||||
shell changes nothing, because the thing being decided is "is this the same machine" and the answer does
|
||||
not depend on the form the caller takes.
|
||||
|
||||
**The other two cases are unchanged and are now legible beside it.** A service exposed to the private
|
||||
network admits the machines on it; a service exposed publicly admits anything. Three cases, three lines,
|
||||
and a reader can see all three at once.
|
||||
|
||||
**[ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md) is superseded and nothing replaces it.**
|
||||
Whether the mesh should check that a grant works is a real question — it reported this machine healthy
|
||||
for eleven hours — but it is a question about what the mesh can say, not about what it should do, and it
|
||||
must stand on its own rather than as the remedy for a rule that was wrong. It is not built.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The three things everything should be able to call are three lines**, and the first is one line
|
||||
rather than one per service, so a service added tomorrow is reachable locally without anybody
|
||||
remembering to say so.
|
||||
- **A form of module stops mattering to the filter.** The 11 modules that are not containers were never
|
||||
affected by this bug and were never the reason it was hard to see; they are the reason the rule should
|
||||
never have mentioned containers.
|
||||
- **The mesh still cannot say when a grant stops working.** That is the live gap, recorded in issue 145
|
||||
and no longer pretending to have an answer.
|
||||
- **What got harder:** nothing. This removes a line per service and replaces it with one.
|
||||
|
||||
## How it is checked
|
||||
|
||||
- **A caller on the machine reaches a service on it, in the input chain**, asserted on that chain's own
|
||||
body — because the forward chain carries the same line in the same words, and an assertion on the
|
||||
whole rendered file passed with the input chain's copy deleted. That is what
|
||||
[ADR 0137](0137-a-machine-says-which-networks-it-routes.md)'s tests already say to do.
|
||||
- **It is one rule, not one per service.** Asserted by rendering two services of different reach and
|
||||
refusing a per-port local line.
|
||||
- **The three reaches render as three lines**, asserted together, so the whole of what the filter says
|
||||
about who may call what is one test.
|
||||
- **The measured case:** from a container on the machine, a service exposed to the private network on
|
||||
that machine answers. This is the outage, and it fails against the rule this replaces.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md) — the filter is the sum
|
||||
of what its modules listen on
|
||||
- [ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md) — why no address is named
|
||||
- [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md) — internal and public,
|
||||
the other two cases
|
||||
- [ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md) — superseded here
|
||||
- [issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: superseded
|
||||
date: 2026-09-29
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 02-DECISIONS/0144-anything-on-a-machine-may-call-anything-on-it.md
|
||||
superseded-by: 02-DECISIONS/0146-connectivity-is-checked-by-name-per-hosting-form.md
|
||||
---
|
||||
|
||||
# 145. A module checks what the mesh claims is reachable, and it checks itself
|
||||
|
||||
## Context
|
||||
|
||||
The mesh asserts three things are callable ([ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md)):
|
||||
what runs on the same machine, another machine's service exposed to the private network, and another
|
||||
machine's service exposed publicly. It has never checked any of them.
|
||||
|
||||
[Issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md):
|
||||
the first of the three was broken for eleven hours and the mesh answered *all heard from, every module
|
||||
current with its source* throughout. Every check it makes is about the relationship between the mesh and
|
||||
a machine — applied, current, containers running — and none about whether anything can reach anything.
|
||||
|
||||
**A first answer was drafted and withdrawn.** [ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md)
|
||||
put the check inside the host, verifying each grant from the consumer's network position. It was
|
||||
superseded because the difference it worked so hard to reproduce — whether a caller sat in a container —
|
||||
was the bug itself. What survives from it is the part that was right: a check run from the wrong place
|
||||
proves nothing, and the mesh's own reports are not evidence about the network.
|
||||
|
||||
**The mesh already has the shape for this and it is a module.** A module can declare a container that
|
||||
runs on a cadence ([ADR 0053](0053-a-step-that-runs-on-a-schedule.md), and three modules already use
|
||||
`*/5 * * * *`), can be given the mesh's roster as a rendered fact — every machine's name, address and
|
||||
this node's own identity, the same mechanism the resolver and the operator's ssh configuration use — and
|
||||
can emit what it found on the bus. Nothing new is needed to build this except the module.
|
||||
|
||||
**What it must not check is the trap.** The obvious probe target is ssh: present on every machine, never
|
||||
closed by design. Dialling it would have passed throughout the outage, because ssh is admitted
|
||||
unconditionally and the thing that broke was a service exposed to the private network. A checker whose
|
||||
probe is unconditionally open measures the one path that cannot fail, which is the failure this whole
|
||||
sequence keeps producing — a check that reads as verification and verifies nothing.
|
||||
|
||||
## Considered Options
|
||||
|
||||
1. **The host verifies each grant** ([ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md)).
|
||||
Superseded. It needed the host to act from another network position, which is machinery that exists
|
||||
only while local calls are filtered wrongly.
|
||||
2. **The control plane dials every node.** Rejected: it sits on one machine and reaches the others by a
|
||||
path no ordinary caller uses. It would have passed throughout the outage.
|
||||
3. **Probe an existing service.** Rejected for the target problem above: the services guaranteed on every
|
||||
machine are the ones that are never closed, so they cannot fail the way the mesh fails.
|
||||
4. **A module on every machine that serves its own probe and dials the others'.** Adopted.
|
||||
|
||||
## Decision
|
||||
|
||||
**A module runs on every machine, serves an endpoint of its own, and dials every other machine's.** The
|
||||
probe is the module's own endpoint, declared reachable over the private network — so the thing being
|
||||
dialled is admitted by exactly the rule that governs every other internally-exposed service, and fails
|
||||
when that rule is wrong. A second endpoint, declared public, does the same for the public path where a
|
||||
machine has one.
|
||||
|
||||
**It checks the three cases the mesh claims, by name:**
|
||||
|
||||
- its **own machine**, by dialling its own machine's address — the case that broke, and the only one that
|
||||
distinguishes a caller on the machine from a caller in one of its containers;
|
||||
- **each other machine over the private network**;
|
||||
- **each machine's public path**, where one is recorded.
|
||||
|
||||
**It resolves before it dials, and says which failed.** A name that does not resolve and a port that does
|
||||
not answer are different faults with different owners, and a checker that reports one sentence for both
|
||||
sends a reader to the wrong place.
|
||||
|
||||
**It runs where the callers run.** The module's own code in its own container, on the cadence the mesh
|
||||
already has, from the same position as every other module on that machine. It is not the host and not the
|
||||
control plane, and that is the whole point.
|
||||
|
||||
**It says what it found and nothing else.** It emits results; it repairs nothing, opens nothing and holds
|
||||
no credential beyond its own. A checker that fixes things is a second control plane.
|
||||
|
||||
**One failure is not a fault.** A machine rebooting is ordinary. A path is reported broken after it has
|
||||
failed on consecutive runs, and the count travels with the result so a reader can tell "briefly away"
|
||||
from "never worked" — the one thing [ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md) got
|
||||
right and worth keeping.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **The mesh gains the ability to be wrong out loud about the network.** Eleven hours becomes two runs.
|
||||
- **It is a module, so it is assigned, built, pushed and reported on like everything else** — no new host
|
||||
capability, no new vocabulary, nothing in the control plane that has to know about checking.
|
||||
- **Its own endpoint is the instrument.** That is what makes it able to fail; it also means the checker
|
||||
must be assigned to a machine before that machine can be checked, and a machine without it is
|
||||
unchecked rather than healthy.
|
||||
- **It cannot check what it cannot be told.** The roster gives it machines; it does not give it every
|
||||
module's endpoints, so this checks the paths the mesh claims and not every grant in the mesh. That is
|
||||
the honest scope of a first one, and the difference is worth saying rather than growing quietly.
|
||||
- **What got harder:** one more module on every machine, and a module whose whole purpose is to fail
|
||||
visibly when something else is wrong. Its own failures will be read as the mesh's, which is the cost of
|
||||
an instrument.
|
||||
|
||||
## How it is checked
|
||||
|
||||
- **It catches the measured outage.** A bed closes the path from a container to a service exposed to the
|
||||
private network on its own machine — issue 145's shape — and the checker reports its own machine
|
||||
unreachable while every other path still reads reachable. This fails against a probe on a port that is
|
||||
never closed, which is the wrong target this record exists to name.
|
||||
- **A machine rebooting is not a fault**: one failed run reports nothing, the count rises and falls.
|
||||
- **A name that does not resolve is reported as that**, not as a port that did not answer.
|
||||
- **It reports and does not act**: asserted by giving it a broken path and checking nothing on the machine
|
||||
changed.
|
||||
- **A machine without the module reads unchecked**, never healthy — asserted on what the mesh says about
|
||||
a machine it is not assigned to.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md) — the three things that must be callable
|
||||
- [ADR 0143](0143-a-consumer-verifies-the-grant-it-is-given.md) — superseded; what survives is that the
|
||||
position matters
|
||||
- [ADR 0053](0053-a-step-that-runs-on-a-schedule.md) — the cadence
|
||||
- [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md) — internal and public,
|
||||
which the probe endpoints declare
|
||||
- [issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: accepted
|
||||
date: 2026-09-29
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 02-DECISIONS/0145-a-module-checks-what-the-mesh-claims-is-reachable.md
|
||||
supersedes: 02-DECISIONS/0145-a-module-checks-what-the-mesh-claims-is-reachable.md
|
||||
---
|
||||
|
||||
# 146. Connectivity is checked by name, per hosting form, with a valid certificate
|
||||
|
||||
## Context
|
||||
|
||||
[ADR 0145](0145-a-module-checks-what-the-mesh-claims-is-reachable.md) decided that a module checks what
|
||||
the mesh claims is reachable, from where the callers are, because the mesh reported four machines healthy
|
||||
for eleven hours while a module could not reach its database
|
||||
([issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)).
|
||||
That decision stands. What it got wrong is everything about *what* is dialled.
|
||||
|
||||
It dialled a raw port on each machine's address. Three things are wrong with that:
|
||||
|
||||
- **A raw port is not how anything in this mesh is reached.** A real caller resolves a name, the proxy
|
||||
answers it, and the proxy reaches the service. A check that dials a port tests the last hop of a path
|
||||
with four hops in it, and the three it skips — resolution, the proxy, the certificate — are where most
|
||||
of the mesh's connectivity actually lives.
|
||||
- **It tested one hosting form.** A module is software that delivers services, and it may deliver them
|
||||
from a container, from a unit the mesh writes for its own code, or from a unit a package ships. Those
|
||||
are three different paths to the same machine, and the outage that produced this was two of them
|
||||
disagreeing. A probe served one way measures one way.
|
||||
- **It said nothing about certificates.** An internal name that resolves, routes and answers over TLS
|
||||
that nothing can verify is not a working path; it is a working path for whoever holds the proxy's
|
||||
trust and nobody else.
|
||||
|
||||
## Decision
|
||||
|
||||
**Each hosting form gets its own endpoint, its own route and therefore its own name.** On every machine:
|
||||
|
||||
| name | what serves it |
|
||||
|---|---|
|
||||
| `connect-docker.<node>.internal` | a container |
|
||||
| `connect-process.<node>.internal` | the mesh's own code, in a unit the mesh writes |
|
||||
| `connect-unit.<node>.internal` | a unit a package ships |
|
||||
|
||||
and the same set under each machine's public domain where it has one — `connect-docker.<domain>` and its
|
||||
siblings. The names are the instrument: a failure reads as *`connect-docker.g14.internal` did not answer*,
|
||||
which says which machine and which hosting form without anybody interpreting anything.
|
||||
|
||||
**Every machine checks every machine, by name, over TLS, verifying the certificate.** Not a port, not an
|
||||
address: resolve the name, connect, complete the handshake, check the certificate against the authority
|
||||
that should have issued it — the mesh's own for an internal name, a public one for a public name. That is
|
||||
the whole path a real caller takes, and each step failing is reported as itself.
|
||||
|
||||
**No name is written anywhere.** The machines come from the roster the mesh already renders as a fact, and
|
||||
the labels are the module's. A machine that joins appears in every other machine's roster on the next
|
||||
push, and they begin checking it without an edit.
|
||||
|
||||
**And the module arrives on a machine because the machine exists, not because somebody assigned it.** A
|
||||
machine that joins and does not have it is worse than unchecked: every other machine is already dialling
|
||||
its names, so it reads as broken everywhere until someone notices. This is the part the mesh cannot
|
||||
currently express — see below — and it is the part that makes the rest safe.
|
||||
|
||||
**What survives from 0145**, unchanged: it reports and repairs nothing; one failure is not a fault and a
|
||||
path is broken after consecutive runs with the count travelling with the result; findings are said on the
|
||||
bus, because a finding in a file on the machine is what this exists to end; and the bus is the one path
|
||||
that cannot report its own failure, so an emit that does not land is written locally and nowhere else.
|
||||
|
||||
## What this needs that the mesh does not have
|
||||
|
||||
Named here rather than assumed, because each is a decision of its own and this record is not the place to
|
||||
make them:
|
||||
|
||||
1. **A module that every machine has.** `ScopeNode` means *at most one holder per node* — an exclusivity
|
||||
rule, not an obligation — and nothing assigns a module at enrolment. Today the resolver, the packet
|
||||
filter, ssh and intrusion prevention are each assigned per machine by hand, which is the same gap
|
||||
wearing different clothes.
|
||||
2. **A container running a module's own bundle.** A `process` runs the mesh's own compiled code with no
|
||||
image; a `container` needs an image of the module's own, which means a Dockerfile — the thing the
|
||||
`bundle` artifact exists to abolish. Nothing in the catalogue runs a bundle in a container, so
|
||||
`connect-docker` has no shape yet.
|
||||
3. **A unit a package ships, for `connect-unit`.** The `service` resource puts an existing unit into a
|
||||
state and deliberately installs none, so this form needs a package that serves a port — and naming a
|
||||
program the machine may not have is
|
||||
[issue 136](../04-ISSUES/136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md).
|
||||
4. **A machine's public domain in the roster fact.** The fact carries each machine's name, mesh name,
|
||||
address and operator account. The public names cannot be composed without the domain.
|
||||
5. **Something that installs the mesh's own root on a machine.** This is
|
||||
[issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md), open
|
||||
since before any of this. Until it is closed, every internal name will fail certificate verification
|
||||
from every machine — correctly, because nothing can verify it. That is the checker working, and it is
|
||||
worth saying in advance so the first run is not read as the checker being broken.
|
||||
|
||||
## Consequences
|
||||
|
||||
- **A failure names the machine and the hosting form.** That is the whole gain over a port: eleven hours
|
||||
became two runs under 0145, and under this it also becomes one line that says where to look.
|
||||
- **The checker surfaces issue 129 immediately**, and will report every internal name unverifiable until
|
||||
it is fixed. A reader must be told that before the first run rather than after.
|
||||
- **Five things must be built before this is what it says it is**, and until they are, what exists is a
|
||||
port dial from one position — useful, and not this.
|
||||
- **What got harder:** a module with three hosting forms of the same trivial service is a strange thing to
|
||||
read. It is justified only because those three forms are how the mesh actually runs software, and a
|
||||
checker that tested one of them would keep the class of outage it exists to catch.
|
||||
|
||||
## How it is checked
|
||||
|
||||
- **A name per hosting form answers from every machine**, asserted by name and not by port.
|
||||
- **A certificate that does not verify is reported as that**, distinctly from a name that does not resolve
|
||||
and a port that does not answer — three faults, three owners.
|
||||
- **A machine that joins is checked by every other machine without an edit**, asserted by adding one to a
|
||||
bed and looking at what the others dial on their next run.
|
||||
- **A machine that joins has the module**, which is gap 1 above and is the assertion that cannot be
|
||||
written yet.
|
||||
- **The measured outage is still caught**: the path from a container to a service on its own machine is
|
||||
closed and `connect-docker.<that node>.internal` fails from that machine while the others still pass.
|
||||
|
||||
## References
|
||||
|
||||
- [ADR 0145](0145-a-module-checks-what-the-mesh-claims-is-reachable.md) — superseded; its core stands
|
||||
- [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md) — the two reaches these
|
||||
names come from
|
||||
- [ADR 0066](0066-public-routing-is-name-agnostic.md) — a label plus a domain, which is why no name is written
|
||||
- [issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md) — what the
|
||||
internal names will fail on until it is closed
|
||||
- [issue 145](../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md)
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
topic: what runs on it
|
||||
status: accepted
|
||||
date: 2026-09-29
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 02-DECISIONS/0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md
|
||||
---
|
||||
|
||||
# 147. A module anchors the mesh's authority on a machine, and takes it away again
|
||||
|
||||
## Context
|
||||
|
||||
The mesh runs its own certificate authority and every internal name is served with a certificate
|
||||
from it. No machine trusts it. On an enrolled, adopted workstation — on the private network,
|
||||
resolving through the mesh's resolver — every internal HTTPS name fails verification with
|
||||
*unable to get local issuer certificate*
|
||||
([issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md)).
|
||||
The certificates are genuine; nothing on the machine has ever been told what issued them.
|
||||
|
||||
The authority's only consumer today is a proxy, which fetches the root into a directory of its own
|
||||
and hands it to one program ([ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md)).
|
||||
That is enough for the proxy and for nothing else: a browser, `git` over HTTPS, `curl`, a package
|
||||
manager and every module that calls another module by an internal name read the machine's trust
|
||||
store, which holds the predecessor's authority and a developer tool's local root, and nothing of
|
||||
the mesh's.
|
||||
|
||||
The predecessor wrote its root into every machine it set up. Removing it was deliberate — an
|
||||
honest failure beats a name that verifies for the wrong reason — and it leaves the mesh with no
|
||||
answer at all until this one lands. It is also what keeps the predecessor alive on the machines
|
||||
that still speak TLS to a mesh name.
|
||||
|
||||
**What makes this a decision rather than a patch** is where the knowledge goes. Two mechanisms in
|
||||
the mesh already write things onto a machine because it is on the private network: `/etc/hosts`
|
||||
and the registry's plaintext trust ([ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md)).
|
||||
Following that precedent, the controller would inject an anchor into every such machine's
|
||||
declaration, and issue 129 proposed exactly that. It would work. It would also put *where this
|
||||
operating system keeps trust anchors* and *which command refreshes its bundles* into the control
|
||||
plane, for a fact the control plane does not have (the root does not exist until the authority has
|
||||
run) and a machine that may have no reason to verify a mesh name at all.
|
||||
|
||||
## Considered Options
|
||||
|
||||
1. **The controller injects the anchor into every machine on the private network**, the
|
||||
`/etc/hosts` and insecure-registry shape. Rejected: being on the network is what makes the
|
||||
registry reachable, and that is why network presence is the right trigger *there* — the trust
|
||||
and the reachability are the same fact. Trusting an authority is not the same fact as being
|
||||
able to reach it, and the anchor's path and the bundle refresh are a property of the machine's
|
||||
operating system, which is the host's half of the mesh, not the controller's.
|
||||
2. **A new host primitive — a `trust-anchor` resource type.** Rejected for now, not on principle.
|
||||
The host's vocabulary should grow when a shape cannot be said with what exists, and this one
|
||||
can: a file and a service already express it, as the packet filter proves
|
||||
([ADR 0140](0140-the-filter-constrains-what-arrives-from-outside.md), whose module writes a
|
||||
unit file and a service and nothing else). The primitive becomes right the moment a second
|
||||
operating system is in play, because the anchor directory and the refresh command are exactly
|
||||
the difference `internal/system` exists to hold. Until then it would be a vocabulary word with
|
||||
one speaker.
|
||||
3. **A module that requires the authority, fetches its root, installs it as an anchor and
|
||||
refreshes the machine's bundles — and removes both when it is no longer assigned.** Adopted.
|
||||
|
||||
## Decision
|
||||
|
||||
**A machine trusts the mesh's authority because a module put its root there, and stops trusting it
|
||||
when that module is taken away.**
|
||||
|
||||
1. **The module requires `internal-acme-ca`** and reads the provider's bound address and the path
|
||||
it serves its root at. It requires nothing else and provides nothing: it is a consumer of the
|
||||
authority like any other.
|
||||
2. **It fetches the root over the mesh's own network, without prior trust**, because there is no
|
||||
prior trust to have — this is the module that establishes it — and the network is what
|
||||
authenticates the fetch ([ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md),
|
||||
the same reasoning that lets the proxy fetch it). What it accepts is checked: a body that is
|
||||
not a certificate fails, and the failure is the module's, not a later handshake's.
|
||||
3. **It installs the root where this machine's TLS clients look, and refreshes the extracted
|
||||
bundles** — the command that does the refresh is an ordinary part of the unit that places the
|
||||
anchor, not a new thing the mesh can be asked to do.
|
||||
4. **Removal is symmetric and is the same unit's business.** Undeclared, the host stops the unit;
|
||||
stopping it removes the anchor and refreshes the bundles again. A machine that leaves the mesh
|
||||
stops trusting the mesh, without anybody remembering to go and look.
|
||||
5. **It is an ordinary assignment.** No machine is given it automatically. A machine that verifies
|
||||
a mesh name is assigned it, and a machine that does not is not — which is the same statement
|
||||
the mesh already makes about every other module, and is why this is not the controller's
|
||||
business.
|
||||
|
||||
**One operating system, said out loud.** The anchor directory and the refresh command in the
|
||||
module today are Arch's. On a machine that is not Arch the unit fails, visibly, rather than
|
||||
writing a file nothing reads. That is the accurate failure, and it is the signal that option 2
|
||||
above has become right.
|
||||
|
||||
## How this is checked
|
||||
|
||||
- **The verification that could not succeed before.** On a machine holding the module, a plain
|
||||
client fetches an internal HTTPS name with no `-k` and no bundle argument and verifies. On a
|
||||
machine without it, the same fetch fails with *unable to get local issuer certificate*. Both
|
||||
halves, because only the pair distinguishes "the anchor works" from "something else already
|
||||
trusted it".
|
||||
- **The removal half, in the same bed:** unassign the module, refetch, and the failure returns.
|
||||
Checking only the arrival is how a trust store fills up with authorities nobody can account for.
|
||||
- **What is deliberately not checked here:** that the authority issues, that a name resolves, that
|
||||
the proxy serves. Those have their own beds, and this module's bed passing for those reasons is
|
||||
the failure mode this record is most exposed to — which is why the negative half is not optional.
|
||||
|
||||
**What this bed is dialled at, and why it is the authority itself.** The authority serves its own
|
||||
API with a certificate it issued, so the handshake under test needs nothing else in the mesh to be
|
||||
right. A trust bed that reached for a routed name through the proxy would be passing or failing for
|
||||
the proxy's reasons and the resolver's.
|
||||
|
||||
**Written, and not yet run** *(2026-09-29)*. The bed is `trust-anchor` in the lab, and it cannot
|
||||
execute: raising a foundation fails before any module is reached, in both bundles that exist
|
||||
([issue 146](../04-ISSUES/146-the-foundation-cannot-be-raised-on-the-bus-the-mesh-runs-on/00-report.md)).
|
||||
So what stands behind this record today is the rendering — the script the machine would run names
|
||||
the authority it was bound to, checked in the control plane's own test suite — and **not** a machine
|
||||
that verified anything. That is a weaker thing than the paragraph above describes, and it stays
|
||||
written this way until the bed runs.
|
||||
|
||||
## Consequences
|
||||
|
||||
The predecessor's authority can be retired from a machine once this module is assigned to it,
|
||||
which is the first time that has been true. `git` over HTTPS to the mesh's forge starts working,
|
||||
so the ssh-only clone URL stops being a rule. A module on any machine can call another module's
|
||||
internal name and verify it.
|
||||
|
||||
What got harder: one more module to assign to a machine that needs it, and the machine's trust
|
||||
store now changes when an assignment changes — which is the point, and is also a thing an operator
|
||||
can be surprised by. The fetch without prior trust is the same exposure ADR 0098 accepted, now on
|
||||
every machine that holds the module rather than only where a proxy runs: anything that can stand
|
||||
in the middle of the mesh's own network at the moment of the fetch can be believed. The mesh
|
||||
already treats that network as the thing it authenticates.
|
||||
|
||||
## References
|
||||
|
||||
- [issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md) —
|
||||
the symptom and the evidence.
|
||||
- [ADR 0098](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md) — a fact made at
|
||||
first start is fetched from its provider; this extends it from one program to the machine.
|
||||
- [ADR 0082](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md) — the precedent
|
||||
this deliberately does not follow, and why it is right where it is.
|
||||
- [ADR 0005](0005-the-node-host.md) — the host is where one operating system's difference lives.
|
||||
- [`03-DESIGN/01-to-be/08-connectivity.md`](../03-DESIGN/01-to-be/08-connectivity.md).
|
||||
@@ -207,9 +207,9 @@ python3 00-META/checks/index.py fail if stale
|
||||
- **0099** — [A step that runs once names what it reads, and runs again when it changed](0099-a-step-that-runs-once-names-what-it-reads.md)
|
||||
- **0110** — [A seat is held by one assignment, from a closed set, and it may deliver a provision](0110-a-seat-is-a-module-assignment-from-a-closed-set.md)
|
||||
- **0112** — [A module definition names no node, no mesh and no path: everything it needs is a requirement the mesh resolves](0112-a-module-definition-names-no-node-mesh-or-path.md)
|
||||
- **0113** — [The vault makes every shared secret, a provider makes resources and data, and the mesh carries both](0113-the-vault-makes-every-secret.md) *(proposed)*
|
||||
- **0113** — [The vault makes every shared secret, a provider makes resources and data, and the mesh carries both](0113-the-vault-makes-every-secret.md)
|
||||
- **0114** — [A credential two parties hold rotates over two credentials; one a single party holds rotates in place, staged; and retiring a credential never removes what it reached](0114-a-shared-credential-rotates-over-two-credentials.md) *(proposed)*
|
||||
- **0115** — [One assignment of a module per node: the module's name is the assignment's identity](0115-one-assignment-of-a-module-per-node.md) *(proposed)*
|
||||
- **0115** — [One assignment of a module per node: the module's name is the assignment's identity](0115-one-assignment-of-a-module-per-node.md)
|
||||
- **0117** — [A machine's uplink is a seat: the mesh configures the manager, never the link](0117-a-machines-uplink-is-a-seat.md)
|
||||
- **0118** — [Undeclaring removes what the mesh made, and gives a unit back the state it was found in](0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md)
|
||||
- **0120** — [A roster fact carries its format as a template: the mesh owns the data, the module owns the format](0120-a-roster-fact-carries-its-format-as-a-template.md)
|
||||
@@ -223,6 +223,11 @@ python3 00-META/checks/index.py fail if stale
|
||||
- **0139** — [A network is forwarded because a module declared it](0139-a-network-is-forwarded-because-a-module-declared-it.md) *(superseded)*
|
||||
- **0140** — [The filter constrains what arrives from outside, and says nothing about a machine's own guests](0140-the-filter-constrains-what-arrives-from-outside.md)
|
||||
- **0141** — [The host delivers its own successor, and versions live side by side](0141-the-host-delivers-its-own-successor.md)
|
||||
- **0143** — [A consumer verifies the grant it is given](0143-a-consumer-verifies-the-grant-it-is-given.md) *(superseded)*
|
||||
- **0144** — [Anything on a machine may call anything on it, and that is the whole of "local"](0144-anything-on-a-machine-may-call-anything-on-it.md)
|
||||
- **0145** — [A module checks what the mesh claims is reachable, and it checks itself](0145-a-module-checks-what-the-mesh-claims-is-reachable.md) *(superseded)*
|
||||
- **0146** — [Connectivity is checked by name, per hosting form, with a valid certificate](0146-connectivity-is-checked-by-name-per-hosting-form.md)
|
||||
- **0147** — [A module anchors the mesh's authority on a machine, and takes it away again](0147-a-module-anchors-the-meshs-authority.md)
|
||||
|
||||
### How it is built
|
||||
|
||||
@@ -232,7 +237,7 @@ python3 00-META/checks/index.py fail if stale
|
||||
- **0014** — [No workspace — each module is a standalone package consuming published dependencies](0014-no-npm-workspace.md)
|
||||
- **0015** — [Applications live in their own repository; the monorepo is for the mesh](0015-applications-live-in-their-own-repository.md)
|
||||
- **0016** — [The lab](0016-the-lab.md)
|
||||
- **0037** — [Where a module lives](0037-where-a-module-lives.md) *(proposed)*
|
||||
- **0037** — [Where a module lives](0037-where-a-module-lives.md)
|
||||
- **0039** — [What the SDK holds, and what it refuses](0039-what-the-sdk-holds-and-refuses.md)
|
||||
- **0068** — [The lab takes requests, one at a time, and runs each from its own copy](0068-the-lab-takes-requests.md) *(proposed)*
|
||||
- **0069** — [A module is a repository and a path within it](0069-a-module-is-a-repository-and-a-path.md)
|
||||
|
||||
@@ -7,8 +7,9 @@ code:
|
||||
- mesh-controller internal/identity/authority.go
|
||||
- mesh-host internal/identity/serving.go
|
||||
- mesh-host internal/apply (the service that reflects a rule set)
|
||||
updated: 2026-09-28
|
||||
updated: 2026-09-29
|
||||
decisions:
|
||||
- 02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md
|
||||
- 02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md
|
||||
- 02-DECISIONS/0140-the-filter-constrains-what-arrives-from-outside.md
|
||||
- 02-DECISIONS/0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md
|
||||
@@ -710,6 +711,22 @@ step, so when the authority moves the root is fetched again and the proxy is rec
|
||||
*How it is checked:* the route-forwarding bed installs the authority, the proxy and a consumer
|
||||
from the catalogue and asserts the routed name is served.
|
||||
|
||||
**And a machine trusts that authority because a module put its root in its trust store**
|
||||
([ADR 0147](../../02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md)). The proxy's fetch
|
||||
answers for the proxy and for nothing else: a browser, `git` over HTTPS, a package manager and
|
||||
every module calling another by an internal name read the machine's own trust store, and the mesh
|
||||
had never written anything there. A module requiring the authority does the whole of it — fetch
|
||||
the root over the mesh network, place it where this machine's TLS clients look, refresh the
|
||||
extracted bundles — and stopping it, which is what being unassigned does, takes the anchor away
|
||||
and refreshes them again. Not the controller's business, because being on the private network is
|
||||
what makes the authority *reachable* and is not the same fact as having a reason to *verify* a
|
||||
mesh name; and because where anchors live and which command refreshes them is one operating
|
||||
system's difference, which is the host's half of the mesh
|
||||
([ADR 0005](../../02-DECISIONS/0005-the-node-host.md)).
|
||||
*How it is checked:* on a machine holding the module a plain client verifies an internal HTTPS
|
||||
name with no bundle argument, and on one without it the same fetch fails to find an issuer — both
|
||||
halves, because only the pair tells the anchor apart from something that already trusted it.
|
||||
|
||||
### What was built
|
||||
|
||||
*2026-08-31.*
|
||||
|
||||
@@ -5,7 +5,7 @@ code:
|
||||
- mesh-controller internal/builder
|
||||
- mesh-controller cmd/mesh-controller (build, build --behind, push, status)
|
||||
- mesh-controller internal/inventory/builds.go
|
||||
updated: 2026-09-21
|
||||
updated: 2026-09-29
|
||||
decisions:
|
||||
- 02-DECISIONS/0090-a-failure-that-repeats-is-said-to-be-stuck.md
|
||||
- 02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md
|
||||
@@ -226,3 +226,34 @@ when the current failure began and how many reports in a row have said it — th
|
||||
id, whatever the words; three make the machine stuck, and `status` says so beside the failure. The host keeps trying — stuck is what the mesh
|
||||
knows, not what the machine is told. *How it is checked:* an inventory test counts three identical
|
||||
reports, a different one, and a clean apply; the status test asserts the word appears.
|
||||
|
||||
## Everything may call what is exposed to it, and local is not a boundary
|
||||
|
||||
*2026-09-29, from an outage that ran eleven hours —
|
||||
[issue 145](../../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md),
|
||||
settled by [ADR 0144](../../02-DECISIONS/0144-anything-on-a-machine-may-call-anything-on-it.md).*
|
||||
|
||||
A grant is four facts and a credential: the provision, the machine, the port, and who the consumer is
|
||||
when it connects. It is the whole mechanism by which anything in the mesh reaches anything else, and it
|
||||
rests on three things being callable — what runs on the same machine, another machine's service over the
|
||||
private network where it is exposed there, and another machine's service over the public network where it
|
||||
is exposed there.
|
||||
|
||||
The filter had two of those. A service exposed to the private network admitted the machines' own addresses
|
||||
on it; a caller on the machine carries such an address, and a caller inside one of that machine's
|
||||
containers carries a bridge address and matched nothing. Measured, same destination and same machine:
|
||||
`src 10.10.0.1` from the machine, `src 172.17.0.8` from a container on it. So a module reaching its
|
||||
database on its own machine's name timed out for eleven hours while the mesh called the machine healthy.
|
||||
|
||||
The second case worked by accident: a caller on another machine arrives over the tunnel carrying that
|
||||
machine's address, which the rule matched. Two of three working is why this read as correct.
|
||||
|
||||
**So local is not a boundary this mesh draws, and the filter says so once.** Traffic that did not arrive
|
||||
from outside the machine and did not arrive over the private network is the machine's own, and is
|
||||
admitted — for every service there, not per service. Whether the caller is a container, a unit or a shell
|
||||
decides nothing, because the question is "is this the same machine".
|
||||
|
||||
A verification mechanism was drafted for this and withdrawn. It would have reported the outage sooner and
|
||||
would not have prevented it, and the part of it that was hard — deciding which network position to check
|
||||
from — existed only because the rule was wrong. Whether the mesh should check that a grant works is still
|
||||
open, in issue 145; it is not the remedy for a configuration error.
|
||||
|
||||
@@ -155,3 +155,17 @@ design document here, and get it back. That check fails today by design.
|
||||
|
||||
**What stands until then** is the signpost, and the honest description of it: reachable, not
|
||||
surfacing.
|
||||
|
||||
## Where this stands, 2026-09-29
|
||||
|
||||
*Added in a grooming pass.* The knowledge base this record is about is the **predecessor's**, and it
|
||||
is no longer reachable from anything: the surface that answered `recall_search` speaks the transport
|
||||
the mesh removed at the cut-over
|
||||
([issue 147](../147-the-operators-tools-still-dial-the-bus-that-was-removed/00-report.md)).
|
||||
|
||||
So the sentence in `README.md` that this record catches — *these documents are still indexed into
|
||||
the knowledge base* — is now wrong twice over: nothing indexed them, and there is nothing to index
|
||||
them into. The record stays open, and its answer is no longer "index this repository somewhere"; it
|
||||
is whatever the mesh grows as its own knowledge surface, if it grows one. Until then the honest fix
|
||||
is the README, which should stop claiming a property nothing provides.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
status: open
|
||||
status: resolved
|
||||
opened: 2026-09-22
|
||||
located-in: []
|
||||
fixed-by:
|
||||
located-in: [mesh-catalog modules/gitea, mesh-controller internal/catalogue/declaration.go]
|
||||
fixed-by: mesh-controller 7352c84, merged in #46 — a module is told its port in a container's environment too, as a file already was
|
||||
amended-design:
|
||||
---
|
||||
|
||||
@@ -39,3 +39,9 @@ the assignment happens to differ.
|
||||
- Should composition refuse an environment value that names a port the module does not fix, the
|
||||
way it refuses other claims a module cannot make?
|
||||
- Which other modules write their own address, with a port, into their environment?
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass rather than by whoever fixed it.* The forge's address follows a moved port the same way every other reader does. Found by
|
||||
reading what the code repositories' commits cite: the fix names this issue and is on `main`. It was
|
||||
not re-verified on a machine, and this record says so rather than implying a run that did not happen.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
status: open
|
||||
status: resolved
|
||||
opened: 2026-09-22
|
||||
located-in: []
|
||||
fixed-by:
|
||||
located-in: [mesh-controller internal/catalogue/declaration.go, mesh-catalog (every routed module)]
|
||||
fixed-by: mesh-controller bdf965d (a route names the endpoint it serves) with `portOfEndpoint` and `AtPublishedPort` — the contribution carries the endpoint's declared port and the machine-side redirection is applied to it like any other
|
||||
amended-design:
|
||||
---
|
||||
|
||||
@@ -45,3 +45,9 @@ precisely because the predecessor holds the usual one.
|
||||
keeping the mapping out of rendered configuration?
|
||||
- What should refuse a declaration whose contributed route names a port nothing on that node
|
||||
listens on?
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass rather than by whoever fixed it.* A route names an endpoint rather than a port, and the redirection that turns a declared port into the published one is applied to contributions too. Found by
|
||||
reading what the code repositories' commits cite: the fix names this issue and is on `main`. It was
|
||||
not re-verified on a machine, and this record says so rather than implying a run that did not happen.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
status: open
|
||||
status: resolved
|
||||
opened: 2026-09-24
|
||||
located-in: [mesh-controller module.json, mesh-host internal/apply]
|
||||
fixed-by:
|
||||
fixed-by: ADR 0142 — the mesh's own components are delivered as binaries on the machine, so the controller is a process; the delivery itself is issue 142
|
||||
amended-design:
|
||||
---
|
||||
|
||||
@@ -84,3 +84,21 @@ restart and run-to-completion semantics — so this would not need host-side wor
|
||||
|
||||
The two do not collapse into one. The controller is not a code-carrying sidecar, and `network: host`
|
||||
is what makes the asymmetry visible here and nowhere else.
|
||||
|
||||
## Answered
|
||||
|
||||
*2026-09-29, in a grooming pass.* This asked a question rather than reporting a defect, and the
|
||||
question was taken: [ADR 0142](../../02-DECISIONS/0142-the-mesh-delivers-its-own-components-as-binaries.md)
|
||||
decides that the mesh's own components — the host, the controller, the catalogue, the builder, the
|
||||
vault — are **binaries on the machine**, delivered by the mechanism
|
||||
[ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md) built, and that
|
||||
third-party software (the store, the registry, the broker) stays a container because an image is the
|
||||
right way to carry somebody else's build.
|
||||
|
||||
So the operating experience this record was written from — every mutating command reached through
|
||||
`docker exec mesh-controller` — is answered, and answered against the container.
|
||||
|
||||
**The delivery is a separate matter and is not this record's.** Step 1 of it is built and no
|
||||
component travels yet; that is
|
||||
[issue 142](../142-the-host-is-the-one-thing-the-mesh-does-not-deliver/00-report.md).
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
status: located
|
||||
status: resolved
|
||||
opened: 2026-09-26
|
||||
located-in: [mesh-sdk src/provisioner, mesh-catalog modules/redis]
|
||||
fixed-by:
|
||||
fixed-by: mesh-catalog bbda88c, merged in #84 — every credential provider says whether it still holds a consumer
|
||||
amended-design:
|
||||
---
|
||||
|
||||
@@ -60,3 +60,9 @@ checks it after the first pass.
|
||||
instance and leaves the gap for the others.
|
||||
- Where does the record of what was applied live, if not in memory? ADR 0114, still
|
||||
proposed, puts rotation state with the vault. The same place may answer this.
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass rather than by whoever fixed it.* A provisioner asks the backend what is there rather than trusting what it remembers doing. Found by
|
||||
reading what the code repositories' commits cite: the fix names this issue and is on `main`. It was
|
||||
not re-verified on a machine, and this record says so rather than implying a run that did not happen.
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
status: located
|
||||
status: resolved
|
||||
fixed-by: mesh-host 1cb8953 and fdc768c — the mesh writes into a marked block of a text file instead of over it
|
||||
opened: 2026-09-26
|
||||
located-in: [mesh-controller internal/catalogue/facts.go, mesh-host internal/apply]
|
||||
---
|
||||
@@ -71,3 +72,9 @@ private network loses that name too.
|
||||
- The host's file resource supports `into: "json"` only; anything else is a whole write.
|
||||
- `node show <node>` on the adopted workstation: `holds file /etc/hosts
|
||||
mesh-wireguard.fact-node-names`, original kept.
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass rather than by whoever fixed it.* A shared hosts file keeps every line that is not the mesh's. Found by
|
||||
reading what the code repositories' commits cite: the fix names this issue and is on `main`. It was
|
||||
not re-verified on a machine, and this record says so rather than implying a run that did not happen.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
status: open
|
||||
status: located
|
||||
opened: 2026-09-26
|
||||
located-in: [mesh-controller, mesh-catalog step-ca]
|
||||
located-in: [mesh-catalog ca-trust]
|
||||
---
|
||||
|
||||
# 129 — nothing makes a machine trust the mesh's own certificate authority
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# Diagnosis
|
||||
|
||||
*2026-09-29.*
|
||||
|
||||
## What was ruled out
|
||||
|
||||
**That something already carries the root and it is only misplaced.** It does not. The authority
|
||||
serves its root at a path beside its ACME directory, and the one thing that fetches it — the route
|
||||
proxy — puts it in a directory of its own and hands it to one program. Nothing has ever written
|
||||
into a machine's trust store. Measured on three converged machines: the anchors present are the
|
||||
predecessor's authority and a developer tool's local root, and on the machines where the
|
||||
predecessor's was deliberately removed, every internal name fails verification.
|
||||
|
||||
**That the private network could carry it, the way it carries the registry's trust.** That is what
|
||||
the report proposed, and it was rejected on consideration rather than on difficulty
|
||||
([ADR 0147](../../02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md), option 1): being on
|
||||
the network is what makes the registry *reachable* and is therefore the right trigger there, while
|
||||
trusting an authority is a separate fact from being able to reach it. The anchor's directory and
|
||||
the command that refreshes the extracted bundles are also one operating system's difference, which
|
||||
is the host's half of the mesh and not the controller's.
|
||||
|
||||
**That it needs a new host resource type.** It does not, today. A file and a service say the whole
|
||||
of it, which the packet filter already proves. The primitive becomes the right answer when a second
|
||||
operating system is in play, and not before.
|
||||
|
||||
## Where it belongs
|
||||
|
||||
A module in the catalogue: it requires `internal-acme-ca`, fetches the root over the mesh's own
|
||||
network, installs it as a trust anchor, refreshes the machine's bundles, and — because being
|
||||
unassigned stops its unit, and stopping the unit is what undoes it — takes both away again.
|
||||
|
||||
The owner is therefore `mesh-catalog`, module `ca-trust`, and nothing in the control plane.
|
||||
|
||||
## The module exists, and this stays open until a machine holds it
|
||||
|
||||
*2026-09-29.* `ca-trust` is in the catalogue and merged
|
||||
([ADR 0147](../../02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md)), and what it renders
|
||||
is checked in the control plane's own suite: the script fetches from the authority it was bound to,
|
||||
and the unit runs it both ways.
|
||||
|
||||
**No machine has been assigned it, and nothing has verified a name because of it.** The bed written
|
||||
for that cannot run ([issue 146](../146-the-foundation-cannot-be-raised-on-the-bus-the-mesh-runs-on/00-report.md)),
|
||||
and the live mesh has not been given the module. So the symptom this record opened on — every
|
||||
internal name failing verification on every machine — is still true everywhere, and the record stays
|
||||
`located` until it is not. Closing it on a module that exists would be closing it on an intention.
|
||||
@@ -1,5 +1,6 @@
|
||||
---
|
||||
status: located
|
||||
status: resolved
|
||||
fixed-by: mesh-host 3112c88 — undeclaring gives a unit back the state it was found in, and removes only a process the mesh made
|
||||
opened: 2026-09-27
|
||||
located-in: [mesh-host internal/apply/apply.go (remove)]
|
||||
amended-design: 02-DECISIONS/0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md
|
||||
@@ -15,7 +16,7 @@ found that the host's `remove` path stops every `service` resource that is no lo
|
||||
delete". `store.Orphans` matches by id alone. So any of these stops the unit:
|
||||
|
||||
- the module is unassigned — by mistake, or to switch it for another;
|
||||
- the node is sent a deliberately-empty declaration ([issue 127](../127-a-declaration-that-shrinks-to-empty-is-skipped-not-sent/00-report.md));
|
||||
- the node is sent a deliberately-empty declaration ([issue 149](../149-a-declaration-that-shrinks-to-empty-is-skipped-not-sent/00-report.md));
|
||||
- a later catalogue version renames the resource's `id`.
|
||||
|
||||
That is right for a service the mesh brought into being. It is wrong for a unit the mesh
|
||||
@@ -64,3 +65,9 @@ something to settle in passing.
|
||||
|
||||
The unassign preview is partly answered — the host's plan names each unit it will stop — and the
|
||||
controller's side is left open.
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass rather than by whoever fixed it.* Undeclaring no longer stops a unit the mesh only reloaded or only kept running. Found by
|
||||
reading what the code repositories' commits cite: the fix names this issue and is on `main`. It was
|
||||
not re-verified on a machine, and this record says so rather than implying a run that did not happen.
|
||||
|
||||
+14
@@ -57,6 +57,20 @@ enrolment path the design guarantees.
|
||||
**The safe direction is not the same as the correct one.** Being more closed than intended broke nothing
|
||||
visible, which is exactly why it went unnoticed for as long as the mesh has been on this machine.
|
||||
|
||||
## What it cost, measured later the same day
|
||||
|
||||
*2026-09-29.* The predecessor's chain was removed, and something it had been carrying went with it. It
|
||||
admitted the private ranges wholesale, which is how a container on the machine reached a port declared
|
||||
for the private network — the mesh's own filter admits the machines' overlay addresses, and a container
|
||||
comes from a bridge. Every module that reached another by the machine's own name had been relying on the
|
||||
predecessor's rule without anybody knowing.
|
||||
|
||||
That is [issue 145](../145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md),
|
||||
and it ran for eleven hours while the mesh reported the machine healthy. The filter is fixed. What this
|
||||
adds to the account here is that "the machine is more closed than the mesh believes" was not the
|
||||
harmless direction after all — it was harmless for everything reached from outside, and an outage for
|
||||
everything reached from within.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Should the host report every place the machine filters from, rather than one kind — the front-end,
|
||||
|
||||
+119
@@ -0,0 +1,119 @@
|
||||
---
|
||||
status: located
|
||||
opened: 2026-09-29
|
||||
located-in:
|
||||
- mesh-controller internal/catalogue/filtering.go (fixed for this instance)
|
||||
- mesh-controller (what status reports, and what it does not ask)
|
||||
fixed-by:
|
||||
amended-design: 03-DESIGN/01-to-be/10-delivery.md
|
||||
---
|
||||
|
||||
# 145 — A machine reads healthy while its modules cannot reach each other
|
||||
|
||||
## What was observed
|
||||
|
||||
Converging the control-node closed every path by which a module on that machine reached another module
|
||||
by the machine's own name. It ran for **eleven hours**. Throughout, the mesh answered:
|
||||
|
||||
```
|
||||
4 machine(s), all doing what they were told, all heard from,
|
||||
running what the mesh would send them, and every module current with its source
|
||||
```
|
||||
|
||||
What was actually happening, from one affected module's own log:
|
||||
|
||||
```
|
||||
Doctrine\DBAL\Exception: Failed to connect to the database:
|
||||
SQLSTATE[08006] connection to server at "novox.internal" (10.10.0.1), port 6852 failed: timeout expired
|
||||
```
|
||||
|
||||
6,154 of them, beginning at the minute of the flip. The web application accepted TCP connections and
|
||||
never answered an HTTP request; a client waited 35 seconds and gave up. Confirmed from a throwaway
|
||||
container on the machine: neither the store nor the forge was reachable on the machine's own address.
|
||||
|
||||
The cause is [issue 144](../144-the-predecessors-rules-outlive-the-firewall-it-was-found-as/00-report.md)'s
|
||||
sibling and is fixed: a port declared reachable from the private network admitted the machines' own
|
||||
overlay addresses, and a container on the machine comes from a bridge address, matching none of them.
|
||||
What this issue is about is the eleven hours.
|
||||
|
||||
**Nothing the mesh reports would have shown it.** Every check the mesh makes passed, because every
|
||||
check the mesh makes is about the relationship between the mesh and a machine:
|
||||
|
||||
- the machine applied what it was sent, and said so;
|
||||
- its declaration digest matches what the mesh would send;
|
||||
- every module's source commit matches what the mesh holds;
|
||||
- every container the declaration names is running.
|
||||
|
||||
None of those asks whether a module can reach what it requires. The mesh knows precisely who requires
|
||||
what — it composes the grants — and never checks that the grant works.
|
||||
|
||||
**Nor would an operator's usual look.** The ports were probed from outside and behaved correctly; the
|
||||
routed services answered; a container's egress to the internet worked. Those are the paths a person
|
||||
checks after changing a firewall, and all three were fine. The broken path was module-to-module over
|
||||
the machine's own name, which nothing routine exercises.
|
||||
|
||||
## Why it matters beyond this instance
|
||||
|
||||
**A mesh that composes a dependency and never tests it can only report on itself.** Every provision the
|
||||
mesh grants is a claim that a consumer can reach a provider. The mesh asserts that claim, delivers
|
||||
credentials for it, and has no mechanism that ever finds out. "Every module current with its source"
|
||||
is a statement about bytes, not about whether anything works.
|
||||
|
||||
**The failure was silent in the direction that hides longest.** A service that will not start is
|
||||
noticed. A service that starts, accepts connections and then cannot reach its database serves errors
|
||||
under a healthy-looking process, and the machine's own report says the container is running — which it
|
||||
is.
|
||||
|
||||
**It is the same shape as [issue 136](../136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md),
|
||||
one level up.** There, a module named a program the machine lacked and everything reported success.
|
||||
Here, the mesh granted a provision the filter refused and everything reported success. Both are the
|
||||
distance between a declaration and the machine, and in both cases the report was about the declaration.
|
||||
|
||||
**And the eleven hours are the measurement, not the bug.** The filter fault was one line and is fixed.
|
||||
What is not fixed is that nothing in the mesh would have told anybody.
|
||||
|
||||
## What was decided
|
||||
|
||||
*2026-09-29, the same day, in two steps and the first was wrong.*
|
||||
|
||||
The first answer was [ADR 0143](../../02-DECISIONS/0143-a-consumer-verifies-the-grant-it-is-given.md):
|
||||
the consumer verifies each grant from its own network position, because whether a caller sat in a
|
||||
container changed whether it could reach the provider. **That difference was the fault**, and the record
|
||||
is superseded. A verification mechanism would have reported this sooner and would not have prevented it,
|
||||
and the part of it that was difficult — deciding which network position to check from — existed only
|
||||
while the rule was wrong.
|
||||
|
||||
The remedy is [ADR 0144](../../02-DECISIONS/0144-anything-on-a-machine-may-call-anything-on-it.md):
|
||||
anything on a machine may call anything on it, said once rather than per service, and asked by the link
|
||||
traffic arrives on rather than the address it carries. Everything should be able to call what runs on the
|
||||
same machine, another machine's service exposed to the private network, and another machine's service
|
||||
exposed publicly. The filter had the second and third and expressed the first as a list of addresses that
|
||||
no container could match.
|
||||
|
||||
**And then the question this issue is actually about was answered on its own terms.**
|
||||
[ADR 0145](../../02-DECISIONS/0145-a-module-checks-what-the-mesh-claims-is-reachable.md): a module on
|
||||
every machine serves an endpoint of its own and dials every other machine's, from the position the
|
||||
callers are in. Its probe is its own endpoint declared reachable over the private network, so it is
|
||||
admitted by exactly the rule that governs every internally-exposed service and fails when that rule is
|
||||
wrong — where a probe on a service every machine has would have passed for all eleven hours, because the
|
||||
services every machine has are the ones never closed.
|
||||
|
||||
Adopted on its merits rather than as the remedy for a configuration error, which is what 0143 was and
|
||||
why it went. The module is written and merged; it is not yet assigned, so every machine currently reads
|
||||
unchecked.
|
||||
|
||||
## Open questions
|
||||
|
||||
- Should a grant be checked? The mesh knows the consumer, the provider, the address and the port, so a
|
||||
reachability check is expressible — but from where: the consumer's machine, as part of a reconcile,
|
||||
or the provider's?
|
||||
- What would it cost to be wrong in the other direction? A check that reports a provision broken while
|
||||
it works is worse than none, because it trains a reader to ignore the report. A provider restarting is
|
||||
ordinary; a consumer between containers is ordinary.
|
||||
- What should `status` say about a machine whose modules cannot reach each other? It currently has one
|
||||
vocabulary for "heard from and current", and that sentence was true the whole time.
|
||||
- Is there a cheaper signal than a probe? The affected module was logging the failure 6,154 times. The
|
||||
mesh reads no module's logs and arguably should not — but something a module could *say* about its
|
||||
own provisions would have surfaced this in minutes.
|
||||
- Does the same blindness apply to the other direction — a provider that lost a consumer's grant and
|
||||
is refusing it? Nothing checks that either.
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
---
|
||||
status: located
|
||||
opened: 2026-09-29
|
||||
located-in: [mesh-host examples + internal/link, mesh-controller internal/broker]
|
||||
---
|
||||
|
||||
# 146 — the foundation cannot be raised on the bus the mesh runs on
|
||||
|
||||
## What was observed
|
||||
|
||||
Raising a first node in the lab, to check a module against a real mesh, fails before any module is
|
||||
reached. Two separate faults, in the two bundles that exist:
|
||||
|
||||
**The older bundle raises a control plane that cannot start.** It brings up the previous broker,
|
||||
and the control plane it then starts says, once every few seconds, for ever:
|
||||
|
||||
```
|
||||
mesh-controller: this control plane has no MESH_BUS_NATS, so it cannot reach the mesh's bus
|
||||
```
|
||||
|
||||
That is the control plane being right. The mesh moved to one bus
|
||||
([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)) and the
|
||||
bundle did not. Every bed that raises a foundation raises this one, so every bed is in this state.
|
||||
|
||||
**The newer bundle, written for the new bus, stops one step earlier.** Its certificate step asks a
|
||||
container to make the broker's certificate:
|
||||
|
||||
```
|
||||
docker run --rm --entrypoint sh -v <the broker's tls volume>:/tls <the bus image> \
|
||||
-c "test -f /tls/tls.crt || (openssl req -x509 ... )"
|
||||
...
|
||||
failed bus-certificate: running the action: docker exited 127
|
||||
```
|
||||
|
||||
127 is *command not found*. The bus's image has a shell and no `openssl`; the previous broker's
|
||||
image had both, which is why the step worked when it was written against that one. Substituting the
|
||||
store's image — the only other image the bundle carries — does not help: it has no `openssl`
|
||||
either. So the step as written cannot succeed with anything the bundle names, and the fault is not
|
||||
one image's: **the bundle asks for a certificate to be made by a tool it never says must be there.**
|
||||
|
||||
Measured 2026-09-29 on a fresh lab machine, both bundles, from bare.
|
||||
|
||||
## Why this is here and not a note in the knowledge base
|
||||
|
||||
The mesh's own foundation is the one thing it cannot raise. Nothing reports that: the bundles are
|
||||
files in a repository, nothing applies them but a person raising a node, and the last thing that
|
||||
did was the hand-driven cut-over
|
||||
([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md), whose
|
||||
work was done on the machines rather than from a bundle). So the state where the mesh cannot make
|
||||
another one of itself is reachable, and was reached, without anything saying so.
|
||||
|
||||
It is also load-bearing for everything else: a lab bed proves a claim by raising a mesh, so while
|
||||
this holds, **no bed can run**, and every "checked in the lab" written from now on is a promise
|
||||
against a suite nobody can execute.
|
||||
|
||||
## What would have prevented it
|
||||
|
||||
- **Something raising the foundation on a schedule, from the bundle, as it is written** — the
|
||||
bundle is the mesh's own installer and nothing installs from it. A bed that raises a first node
|
||||
is exactly that check, and it is the bed that cannot run.
|
||||
- **A step naming what it needs.** The certificate step names an image and assumes a program inside
|
||||
it. An action that said which tool it requires would have failed at the declaration rather than
|
||||
at 127 on a machine.
|
||||
|
||||
## Evidence to carry into diagnosis
|
||||
|
||||
- `mesh-host examples/foundation-first-node.lock` — the previous broker, no `MESH_BUS_NATS`.
|
||||
- `mesh-host examples/foundation-first-node-nats.lock` — the new bus; `bus-certificate` and its
|
||||
`verify` both run `openssl` in the bus's image.
|
||||
- The bus image the bundle pins has `sh` and no `openssl`; the store's image likewise.
|
||||
- The lab rewrites a bundle's registry-prefixed third-party references to upstream ones for a
|
||||
machine with an uplink (`test/integration/harness.ts`); the new bundle's bus reference needed
|
||||
that rule added, which is done and is not this issue.
|
||||
+184
@@ -0,0 +1,184 @@
|
||||
# Diagnosis
|
||||
|
||||
*2026-09-29, by raising a first node in the lab over and over and writing down each thing it hit.*
|
||||
|
||||
Not one fault. **Four, stacked**, each hidden behind the one before it, and every one of them the
|
||||
same shape: a step that was right while the mesh ran on the previous broker and was never asked a
|
||||
question again after the bus changed. Nothing had raised a foundation since, so nothing said so.
|
||||
|
||||
## 1 — the bundle's bus image is named for a registry that is gone *(fixed)*
|
||||
|
||||
The newer bundle pins `<a lab registry>/nats@…`, which resolves nowhere outside the lab that
|
||||
raised that registry. The lab already rewrites the store's and the previous broker's references to
|
||||
upstream ones for a machine with an uplink; the bus had no such rule because no bed had ever tried
|
||||
to raise this bundle. Added (`mesh-lab test/integration/harness.ts`). The digest is the bundle's
|
||||
own — what the registry served was a copy, so the same digest resolves upstream, and this is a
|
||||
prefix being removed rather than a reference being replaced.
|
||||
|
||||
## 2 — the bus's certificate was made by a tool the bus does not have *(fixed)*
|
||||
|
||||
```
|
||||
failed bus-certificate … docker exited 127
|
||||
```
|
||||
|
||||
The step ran `openssl` inside the broker's image. The previous broker's image carried it; the bus's
|
||||
does not — it is Alpine with a shell and no `openssl` — and neither does any other image the bundle
|
||||
names, so there was nothing to substitute. **The program that needs the certificate now makes it**:
|
||||
`mesh-controller broker certificate --into <dir>`, with `--check` as the step's verify. The
|
||||
controller is already on the machine at that point (the schema step ran it) and needs nothing from
|
||||
the image it writes into. Self-signed, as before and on purpose — a host pins this server's exact
|
||||
certificate ([ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)) and at that moment
|
||||
there is no authority to ask. Idempotent, because a second certificate is one every host that
|
||||
pinned the first no longer believes. It runs `--user 0:0`: the volume is root's, and the control
|
||||
plane's image runs as nobody, which is right for the long-lived server and wrong for a one-shot
|
||||
writing into a fresh volume.
|
||||
|
||||
## 3 — enrolment dialled TLS at a bus that speaks first *(fixed)*
|
||||
|
||||
```
|
||||
mesh-host: cannot reach the broker at …:5671: tls: first record does not look like a TLS handshake
|
||||
```
|
||||
|
||||
Enrolment opened a raw TLS connection to check the pinned certificate before saying anything. NATS
|
||||
speaks its own protocol and upgrades afterwards, so the handshake met a plaintext greeting. The pin
|
||||
was never the problem: the same pinned configuration is handed to the client that presents the
|
||||
token, and the verification runs inside *that* handshake — so what
|
||||
[ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md) requires still holds, and holds
|
||||
better, because the one-time secret is sent only after the certificate has been checked. The raw
|
||||
dial is gone from the enrolment path and kept only as what its tests always proved: that a wrong
|
||||
certificate is refused before a byte of application data is sent.
|
||||
|
||||
**Then, immediately behind it:**
|
||||
|
||||
```
|
||||
mesh-host: this token is for the "" bus, and the mesh's bus is nats
|
||||
```
|
||||
|
||||
The enrolment left the transport empty and meant *whatever the mesh runs today*, which was true
|
||||
while two buses existed and became a refusal the moment one did. The host knows which bus the mesh
|
||||
runs; it says so now.
|
||||
|
||||
## 4 — a first node cannot be let onto its own bus *(open, and this is the real one)*
|
||||
|
||||
```
|
||||
mesh-host: cannot reach the bus at …:5671 as anchor: nats: Authorization Violation
|
||||
```
|
||||
|
||||
The bus's user list is a file beside its configuration. The installer carries the first one — the
|
||||
controller's own account at a bootstrap password — and **the controller composes every user after
|
||||
that** (design 25 §6; the controller's own test asserts the carried list matches what it would
|
||||
derive). On the running mesh that composition reaches the bus because the bus is a *module*, with
|
||||
the list delivered to it the way anything is delivered to a module.
|
||||
|
||||
At genesis there is no module. The foundation's bus is raised by the installer, the control plane is
|
||||
given no way to write beside its configuration — it mounts the certificate and nothing else — and so
|
||||
the account a joining node needs cannot come into existence. **The first node cannot join the mesh
|
||||
it just raised.**
|
||||
|
||||
That is not a line to fix in a bundle. It is the open half of the mesh delivering its own components
|
||||
([ADR 0142](../../02-DECISIONS/0142-the-mesh-delivers-its-own-components-as-binaries.md)) and of the
|
||||
bus becoming a module: either the installer's bus is raised as the module the mesh will go on
|
||||
managing, or genesis carries a user list that includes the first node's enrolment and the controller
|
||||
takes over from there. Both are decisions, not patches, and both belong to the genesis step that was
|
||||
deliberately left until last.
|
||||
|
||||
## 5 — the composed user list has to be placed by hand at genesis *(fixed)*
|
||||
|
||||
The account a token is the password of is **not recorded at all**: the composer names an enrolment
|
||||
user for every machine with a live token, nothing minted a credential for it, and the composition
|
||||
left it out as a user with no password. The comment above the issuing code already claimed
|
||||
otherwise — *"the account is created before the token is handed over"* — which is how it went
|
||||
unnoticed. Issuing a token now records that account, with the token's own secret as its password,
|
||||
because that is the string the machine will present.
|
||||
|
||||
Placing it is the other half. The list reaches the machine running the bus in that machine's
|
||||
declaration, which a machine that has not enrolled does not get, so at genesis it cannot arrive
|
||||
that way. **The control plane composes and says what it composed** — `broker accounts`, to standard
|
||||
output — and whoever is raising the machine writes it beside the bus's configuration and makes the
|
||||
server re-read it. Twice, because two accounts come into existence at different moments: the
|
||||
enrolment when the token is issued, and the machine's own when it enrols. A control plane that
|
||||
wrote the file itself would have to know where the bus keeps its configuration and how to make it
|
||||
reload, which is the module's knowledge and is what the module takes over on the first push.
|
||||
|
||||
With that, **a first node enrols against the bus it just raised** — measured, from bare, in the
|
||||
lab.
|
||||
|
||||
## 6 — and is enrolled twice, keeping a credential the mesh has replaced *(fixed)*
|
||||
|
||||
```
|
||||
mesh-controller: enrolled anchor
|
||||
mesh-controller: enrolled anchor (the same second)
|
||||
```
|
||||
|
||||
One `enrol` on the machine, two enrolments in the control plane. Each mints the node a fresh bus
|
||||
password and returns it; the machine keeps the answer to the first, and the mesh keeps the hash of
|
||||
the second. The machine then reconnects for ever as a user whose password the mesh rotated out from
|
||||
under it — *authentication error - User "node.anchor"* on the bus, `Authorization Violation` in the
|
||||
host's log, and a node that never reports.
|
||||
|
||||
What is ruled out: the host asking twice — it asks again only when the mesh says *try again*, and
|
||||
a refused attempt is not logged as an enrolment. Redelivery by the consumer — there is one
|
||||
consumer, its acknowledgement window is thirty seconds, and the handler is quick.
|
||||
|
||||
What is left: the client re-publishing when an acknowledgement is slow, which is what its defaults
|
||||
do. That was addressed by giving the publish a message id derived from its own bytes, so the stream
|
||||
discards the copy — **and the duplicate survived it**, so either the id is not reaching the stream
|
||||
or the second copy is not a copy. This is where the trail stops.
|
||||
|
||||
Worth saying plainly: **the mint is the fragile part, not the delivery.** An enrolment answered
|
||||
twice is survivable if the answer is the same both times, and it cannot be — the mesh keeps only
|
||||
the hash, so a second answer is necessarily a different credential.
|
||||
|
||||
**Found, and it is not about enrolment at all** *(fixed)*. The bus's own counters settled it: one
|
||||
message published, one held in the stream, one delivery, nothing redelivered — and the controller
|
||||
enrolled the machine twice. So the handler ran twice on one delivery.
|
||||
|
||||
A push consumer delivers onto an ordinary subject, and **everything subscribed to that subject gets
|
||||
a copy**. The controller holds a consumer called `controller` on CONTROL and another called
|
||||
`controller` on EVENTS, and the delivery subject was derived from the consumer's name alone — so
|
||||
both were `_DELIVER.controller`, the one process held both subscriptions, and every message from
|
||||
either stream was acted on twice.
|
||||
|
||||
Enrolment is where it drew blood, because enrolling twice mints twice and the second credential
|
||||
replaces the first. But it applied to **every report and every event the controller follows**, and
|
||||
it is the kind of fault that leaves no trace: nothing is redelivered, no counter is wrong, the work
|
||||
simply happens twice. The comment in the receiving code about a merge that ran the whole catalogue
|
||||
five times over on 2026-09-28 is the same shape seen from the other end.
|
||||
|
||||
The stream is in the delivery subject now, because the pair is what identifies a consumer — the
|
||||
server scopes a durable's name to its stream, and this subject was the one place that scoping was
|
||||
dropped. A subscriber's permission gains the same shape, keeping the bare name so an existing
|
||||
consumer keeps working until the controller's next assertion moves it.
|
||||
|
||||
*How it is checked:* the consumers the mesh asks for are asserted to deliver onto distinct subjects,
|
||||
in the controller's own suite. Against a server it would be invisible, which is the point.
|
||||
|
||||
## Where it belongs
|
||||
|
||||
`mesh-host` (the bundle and the enrolment path) and `mesh-controller` (the certificate command, and
|
||||
the composition that cannot reach the bus at genesis). Three of the four are fixed on branches; the
|
||||
fourth is the genesis work.
|
||||
|
||||
## What made it slow, and what was changed so it is not
|
||||
|
||||
Six faults behind one another, each found by raising a machine and reading what it said. What cost
|
||||
the most was not the faults:
|
||||
|
||||
- **Every bed's own instructions named the bundle that cannot work**, so the first three attempts
|
||||
ended in a control plane crash-looping on a missing bus. They name the working one now.
|
||||
- **A host binary built without its system** refuses everything it is given with *this host was
|
||||
built for ""*, which reads like a broken bundle. The lab's README says so.
|
||||
- **`make image` in the control plane had been broken for as long as its base was pinned**: the
|
||||
Dockerfile's fallback is a Go older than the module asks for, and the pipeline never saw it
|
||||
because the pipeline passes the declared base in. It reads the base from the manifest now.
|
||||
- **Leaving the machine standing is what answers the question.** Every finding above came from
|
||||
shelling in afterwards — the host's log, the bus's log, the file the bus was actually handed —
|
||||
and none from the test's own output, which says only that nothing converged. The bed takes
|
||||
`MESH_LAB_KEEP`, and the README says to reach for it first.
|
||||
|
||||
## What it cost, for the next person
|
||||
|
||||
Every lab bed still names `foundation-first-node.lock` in its own instructions, and that bundle
|
||||
raises the previous broker with a control plane that refuses to start without `MESH_BUS_NATS`. Until
|
||||
the fourth fault is answered and the two bundles become one, a bed runs with `MESH_LAB_BUNDLE`
|
||||
pointing at the NATS bundle by hand, and stops at the enrolment.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
status: located
|
||||
opened: 2026-09-29
|
||||
located-in: [nothing in the mesh — the surface in use is the predecessor's, installed on the workstation]
|
||||
---
|
||||
|
||||
# 147 — the operator's tools still dial the bus that was removed
|
||||
|
||||
## What was observed
|
||||
|
||||
Every tool call an operator makes against the mesh fails, on every machine, with the same answer:
|
||||
|
||||
```
|
||||
AMQP not connected — cannot reach hal/mesh@novox
|
||||
AMQP not connected — cannot reach hal/mesh@shanks
|
||||
```
|
||||
|
||||
The mesh moved to one bus and the previous transport was deleted
|
||||
([ADR 0131](../../02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md), cut over
|
||||
2026-09-28). The surface an operator drives the mesh through — the tool bridge their assistant
|
||||
speaks to — still opens an AMQP connection, so it cannot reach anything. Not one node answers,
|
||||
including the machine the operator is sitting at.
|
||||
|
||||
**What that leaves.** The mesh itself is healthy: nodes are current, modules run, the bus carries
|
||||
the mesh's own traffic. What is gone is the way a person asks it anything. Every question — what a
|
||||
node runs, what is assigned, what a module's settings are — has to be asked by opening a shell on
|
||||
the machine and running the control plane's binary inside its container, which is precisely the
|
||||
path the tool surface exists to remove, and which nothing checks, records or permits.
|
||||
|
||||
It also silently changes how work gets done: an assistant told to use the mesh's tools finds them
|
||||
dead, falls back to `ssh` and `docker exec`, and the operator discovers the fallback rather than
|
||||
the fault.
|
||||
|
||||
## Why this is here and not a note in the knowledge base
|
||||
|
||||
The rule is that everything happens over the mesh's bus. A surface that cannot reach that bus is
|
||||
that rule enforced by nothing — and the mesh reports itself healthy throughout, because what broke
|
||||
is not a module, a node or a provision but the thing standing outside asking them questions.
|
||||
|
||||
The same cut-over removed the assistant's long-term memory (`recall`, `memorize`) for the same
|
||||
reason, which is why lessons from the last two days were written into this repository by hand.
|
||||
|
||||
## What would have prevented it
|
||||
|
||||
- **The tool surface as a consumer of the bus like any other**, so moving the bus moves it — rather
|
||||
than a separate bridge with its own connection settings that nothing resolves.
|
||||
- **A check that a tool call reaches a node**, run where the mesh's other checks run. Every check
|
||||
the mesh makes today is about the relationship between the mesh and a machine; none asks whether
|
||||
a person can ask it anything ([issue 145](../145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md),
|
||||
the same shape one level out).
|
||||
|
||||
## Diagnosed at once, because the answer was in the configuration
|
||||
|
||||
**The surface is not the mesh's.** The tool server the operator's assistant speaks to is the
|
||||
predecessor's brain, installed on the workstation and started as a local process, with the
|
||||
predecessor's broker URL — `amqp://…@<the control node>` — written into the assistant's own
|
||||
configuration. Nothing about it is a module: it has no manifest, no assignment, no seat, no account
|
||||
on the mesh's bus, and the mesh has never known it exists.
|
||||
|
||||
So nothing regressed. The mesh removed a transport that this program still dials, and the program
|
||||
was never part of the mesh to be moved. **The mesh has a tool model** — `tools` in a manifest, the
|
||||
calls a seat accepts, the subjects a module answers on, and a control-plane command that asks one —
|
||||
and **nothing publishes an operator-facing surface onto it.** What an operator uses is the thing
|
||||
that came before, kept alive by a URL in a file.
|
||||
|
||||
That is the issue, and it is larger than a broken connection: the way a person drives this mesh is
|
||||
outside the mesh.
|
||||
|
||||
## Evidence to carry into diagnosis
|
||||
|
||||
- The failure text names `hal/mesh@<node>`, so the bridge is resolving a node and then dialling the
|
||||
old transport.
|
||||
- It fails identically for the local machine, which rules out reachability and points at the
|
||||
transport alone.
|
||||
- The mesh's own traffic over the new bus is unaffected: nodes report, declarations apply.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
status: open
|
||||
opened: 2026-09-29
|
||||
located-in: [mesh-controller cmd/mesh-controller]
|
||||
---
|
||||
|
||||
# 148 — a manifest outside this catalogue has no check
|
||||
|
||||
## What was observed
|
||||
|
||||
A module's manifest is validated by a **test** — `internal/catalogue`'s suite parses every manifest
|
||||
in the catalogue checkout beside it and fails on one it cannot resolve. That works, and it is how
|
||||
several real faults were caught before a machine saw them.
|
||||
|
||||
It is available to exactly one repository: this one. Somebody describing their own application in
|
||||
their own repository — the case
|
||||
[ADR 0037](../../02-DECISIONS/0037-where-a-module-lives.md) calls *the case that matters most* —
|
||||
has no check at all. They write a manifest, register it with a running mesh, and find out whether
|
||||
it is valid when the mesh refuses it, or later, when a machine applies something that resolved and
|
||||
should not have.
|
||||
|
||||
The same record asks for the answer: **a `module check` command on the control plane's binary**, so
|
||||
a manifest is checked by the tool rather than by a test that imports the tool's internals.
|
||||
|
||||
## What would have prevented it
|
||||
|
||||
Nothing prevents this; it was noticed and left. ADR 0037 named it on 2026-09-01 and the record sat
|
||||
`proposed` until 2026-09-29, so the missing half was never anybody's task.
|
||||
|
||||
## Evidence to carry into diagnosis
|
||||
|
||||
- `mesh-controller/internal/catalogue` — `ParseManifest` and `CatalogueProblems` are the check, and
|
||||
both are internal.
|
||||
- The catalogue-wide test is `TestEveryCatalogueManifestDeclaresWhatItMounts` and its siblings; they
|
||||
take a path from `MESH_CATALOG`, so the mechanism is already path-driven and not repository-bound.
|
||||
- `mesh-controller module add` refuses a bad manifest at registration, which is the same check far
|
||||
too late: by then it is in a running mesh's records.
|
||||
+22
-3
@@ -1,10 +1,15 @@
|
||||
---
|
||||
status: located
|
||||
status: resolved
|
||||
opened: 2026-09-27
|
||||
located-in: [mesh-controller cmd/mesh-controller/push.go]
|
||||
located-in: [mesh-controller cmd/mesh-controller/push.go, mesh-controller cmd/mesh-controller/sendable.go]
|
||||
fixed-by: mesh-controller sendable.go and push.go — an empty declaration is sent carrying `owns_nothing`, and the host refuses an empty body that does not carry it
|
||||
---
|
||||
|
||||
# A declaration that shrinks to empty is skipped, so the node keeps what it should drop
|
||||
# 149 — a declaration that shrinks to empty is skipped, so the node keeps what it should drop
|
||||
|
||||
*Opened as 127 and renumbered on 2026-09-29: two records were given that number on the same day.*
|
||||
*The other kept it, because three documents and three source files cite it by number and nothing
|
||||
cited this one but a decision and a sibling issue, both corrected with this move.*
|
||||
|
||||
## What was observed
|
||||
|
||||
@@ -37,3 +42,17 @@ mean "own nothing", which the host already applies correctly when it receives on
|
||||
|
||||
On ace, one command drops it permanently (the corrected controller never re-composes it):
|
||||
`sudo ufw delete allow 5671`. At ace's converge it would clear on its own.
|
||||
|
||||
## Closed
|
||||
|
||||
*2026-09-29, in a grooming pass.* Both halves are on `main` and both name this issue.
|
||||
|
||||
- The control plane **sends** it: a declaration that composes to no resources goes out with
|
||||
`owns_nothing`, and `push` says *sent, not skipped*.
|
||||
- The host **refuses an empty body that does not carry it**, so a truncated or mis-composed
|
||||
declaration can never be read as "own nothing" — which is the failure the fix had to avoid while
|
||||
making the empty case expressible.
|
||||
|
||||
Closed by reading the code rather than by watching a machine let go of a stray resource; the record
|
||||
says so rather than implying a run.
|
||||
|
||||
Reference in New Issue
Block a user