novox/hq

Files

T

jschoubben 8d9282d86b Resolve the ingress gap: a route is a grant

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.

2026-08-27 00:22:52 +02:00

5.5 KiB

Raw Blame History

status, date, deciders, reconstructed, extends

status	date	deciders	reconstructed	extends
accepted	2026-08-27	jochen	false	0030-the-repository-structure.md

48. The substrate is named

Context

The substrate 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'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 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

Ingress was a real gap rather than a naming one, and it is closed by ADR 0049: 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). 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 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 — the test these satisfy.
ADR 0001 — why the bus speaks AMQP.
ADR 0046 — pinning by digest, which needs a name.
ADR 0044 — why the store is the one that cannot simply be swapped.

5.5 KiB Raw Blame History