2026-09-05 10:27:11 +00:00
1 changed files with 35 additions and 0 deletions
@@ -250,6 +250,41 @@ name and overlay address.
 database before its own DNS existed; with [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
 nothing needs a name before the link, and a fallback nothing needs is a path nothing tests.

+### Names, and what a container can see
+
+*2026-08-31, from a container that could not resolve a name every machine could.*
+
+Internal names are `<node>.internal` — the suffix is the one IANA reserved in 2024, so a name that
+leaks into a public resolver fails rather than reaching a stranger's machine. They are computed
+centrally, because a name set needs every node at once, and written to each machine's hosts file.
+
+**A file rather than a resolver**, and the reasoning holds: it works on every Linux, needs no
+package, and has no failure mode of its own. The stated trigger for a daemon was *names that are
+not one-per-node* — service names, wildcards.
+
+**But a container does not inherit the machine's names.** It gets its own hosts file holding only
+its own hostname. So every name the mesh wrote was invisible to the majority of things that need
+one — and *on the machine it always worked*, which is exactly what made it easy to miss. It was
+found by a database client on one node failing to resolve another node, on a mesh where both names
+were correct and present on both machines.
+
+**So the mesh gives its names to the containers it declares**, written into each container's own
+hosts file by the runtime. That extends the file decision rather than overturning it. Given by the
+mesh and not chosen by a module: a module that listed the machines would go stale the day one
+joins, and a module that did not would be one whose containers cannot reach anything by name.
+
+**The boundary, which is deliberate and worth stating:** *declared* containers. A container
+somebody starts by hand is not the mesh's to configure, and reaching into every container on a
+machine — declared or not — is what a nameserver in `resolv.conf` would be for.
+
+**That is now the second reason to want a resolver**, and it is a different one from the trigger
+above. Both remain unmet needs rather than plans:
+
+| | |
+|---|---|
+| names that are not one-per-node | `postgres.internal` meaning *wherever the database is* |
+| containers the mesh did not declare | anything a person or another tool starts on a node |
+
 ## 3 — Exposure

 Settled by [ADR 0007](../../02-DECISIONS/0007-connectivity.md); summarised here because