jschoubben
8d9282d86b
ADR 0048 named ingress as an unclosed hole -- nothing said what terminates TLS, how a public name reaches a container, or which tier owned it. Resolving it needed no new concepts, which is why it survived: nobody had applied the rules already written to it. Ingress is not substrate. The control plane does not need a route to start, and no node needs one to reach it -- the node dials out and has no listening control surface. It grants itself a route afterwards, like a bucket. A route is an instantiation edge under ADR 0044. The direction mirrors a database -- the consumer supplies a target and receives a name rather than credentials -- but it is the same edge. The substantive finding is that exposure is three facts at two scopes: name resolution and certificate issuance need to know which node is publicly reachable, and only the proxy mapping is a single machine's business. That is why it belongs to the connectivity context, and why Traefik doing all three on the node is wrong. Which matters beyond tidiness: research 006 counted traefik as one of two modules opening a direct Postgres connection, reading nodes and mesh_ca. That violates 0037, 0045 and 0039 at once, and is why every node permanently holds a credential to the control plane's database. Deriving the config centrally and delivering it as `file` resources removes it, costs zero new host vocabulary, and closes the set 0039 identified -- wireguard was the other. Left open deliberately: the mesh's internal CA is the other thing traefik reads, and it belongs to the link's mutual authority, not to exposure. Conflating the two is what made the gap hard to see. Also fixes an inconsistency from the previous commit: 06 still claimed the virtual host was raised from the bundle. Proposed, not accepted -- for review.
98 lines
5.5 KiB
Markdown
98 lines
5.5 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-27
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 0030-the-repository-structure.md
|
|
---
|
|
|
|
# 48. The substrate is named
|
|
|
|
## Context
|
|
|
|
[The substrate](../03-DESIGN/01-to-be/07-the-substrate.md) is defined by a test — *what the
|
|
control plane consumes and cannot grant itself* — and the design layer describes its members
|
|
entirely by role: a relational store, a message bus, an object store, an image registry.
|
|
|
|
**No design document names a product.** Postgres appears in zero of them. The names occur only
|
|
in the as-is layer and in research, describing what already runs.
|
|
|
|
That is a gap rather than a discipline. The rule it came from —
|
|
[`01-RESEARCH`](../01-RESEARCH/README.md)'s *research never identifies the mesh it observed* —
|
|
is about node names and domains, not about software. Nothing is protected by declining to write
|
|
*Postgres* in a public repository, and something is lost: a design that never names a product
|
|
does not record that the choice was made.
|
|
|
|
Two costs, both already accrued:
|
|
|
|
- **`substrate.lock` cannot be written from the design.** It pins images by digest, and a digest
|
|
belongs to a named image.
|
|
- **A reader cannot tell a settled choice from an unexamined one.** "A relational store" reads
|
|
the same whether the store was chosen deliberately or never considered.
|
|
|
|
## Decision
|
|
|
|
**The substrate is named, and the names are these:**
|
|
|
|
| Role | Product | Why |
|
|
|---|---|---|
|
|
| relational store | **PostgreSQL** | In use, understood, and the provisioning model already assumes its notions of database, role and schema. |
|
|
| message bus | **LavinMQ** | In use, speaks AMQP, which is what [ADR 0001](0001-nodes-communicate-over-a-broker.md) assumes. Interchangeable with other AMQP brokers at the protocol level, which is what makes it a safe choice rather than a locked-in one. |
|
|
| object store | **MinIO** | In use, speaks the S3 protocol, which is the closest thing to a portable object-store interface. |
|
|
| image registry | **the OCI distribution registry** | In use, and the format is the standard rather than a vendor's. |
|
|
| container runtime | **Docker** | In use. Podman is the plausible alternative and was not chosen for any deficiency — Docker is what the machines run today and what the current tooling assumes. |
|
|
|
|
### Outside the substrate
|
|
|
|
The gap is not only the substrate's. The design layer names roles for these too, and the same
|
|
correction applies — a role is a legitimate abstraction, but the product belongs beside it:
|
|
|
|
| Role, as the design says it | Product | Tier |
|
|
|---|---|---|
|
|
| **the forge** | **Gitea** | a hosted workload — the mesh builds from it but does not need it to run |
|
|
| **the coordinator** | the mesh's own pipeline | tier 2 — part of the control plane, not a product |
|
|
| **ingress** — *exposure*, *certificates* | **Traefik** | not substrate — [ADR 0049](0049-a-route-is-a-grant.md) |
|
|
|
|
**Ingress was a real gap rather than a naming one**, and it is closed by
|
|
[ADR 0049](0049-a-route-is-a-grant.md): applying the same test shows it is **not** substrate, and
|
|
a route is an ordinary grant. Recorded here because finding it was the point — naming the
|
|
products is what made the unnamed role visible.
|
|
|
|
**Identity is deliberately absent.** Whether an identity provider is substrate at all depends on
|
|
whether the control plane delegates authentication, which is undecided
|
|
([`07-the-substrate.md`](../03-DESIGN/01-to-be/07-the-substrate.md)). Naming a product before
|
|
deciding whether the role exists would be the mistake this record is correcting, in reverse.
|
|
|
|
**The role and the product are both written.** A design says *the relational store (PostgreSQL)*
|
|
rather than one or the other. The role is what the argument turns on; the product is what gets
|
|
installed, and a reader needs both.
|
|
|
|
## Consequences
|
|
|
|
- **`substrate.lock` becomes writable.** It pins named images by digest, which was impossible
|
|
while the design refused to say which images.
|
|
- **Continuity is the argument, and it is a real one.** Every choice here is what already runs.
|
|
Nothing was re-litigated, because nothing about the new shape gives a reason to — and changing
|
|
a substrate service is a migration of the mesh's own state, which is not a cost to pay for
|
|
novelty.
|
|
- **Protocols, not products, are what the design depends on.** The bus is reached over AMQP, the
|
|
object store over S3, the registry over the OCI protocol. Replacing a product is then a
|
|
substrate migration rather than a redesign — which is the property that makes naming them safe
|
|
rather than a commitment that cannot be revisited.
|
|
- **The relational store is the exception**, and it should be said. The provisioning model uses
|
|
databases, roles and schemas as Postgres means them, and
|
|
[ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) already records that
|
|
two stores from different vendors are not substitutable for a consumer. Replacing it is not a
|
|
swap.
|
|
- **The rule that caused this is narrowed, not repealed.** Research still does not identify the
|
|
mesh it observed — node names, domains, addresses. Product names were never in scope, and the
|
|
over-application cost the design layer its concreteness.
|
|
|
|
## References
|
|
|
|
- [`07-the-substrate.md`](../03-DESIGN/01-to-be/07-the-substrate.md) — the test these satisfy.
|
|
- [ADR 0001](0001-nodes-communicate-over-a-broker.md) — why the bus speaks AMQP.
|
|
- [ADR 0046](0046-the-installer-fetches-what-it-pins.md) — pinning by digest, which needs a name.
|
|
- [ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) — why the store is
|
|
the one that cannot simply be swapped.
|