jschoubben
a72fea5342
The lab provides the underlay; the mesh builds the overlay. This is the boundary that decides whether the lab is worth having: a scenario that assigns overlay addresses, elects the hub and writes peer configuration certifies its own work — if the mesh's peering is broken, that scenario still comes up green. The most valuable thing the lab can test is exactly the part pre-building would replace. So a scenario declares what a hosting provider and a home router would provide: segments, which machine sits where at which address, what NAT is between them, which ports are forwarded, which machines are detached. It declares nothing about overlay addresses, hubs, peering, names or certificates, all of which become outcomes to observe. The declaration has four parts — segments, machines, place, snapshot — and the two scenario classes differ only in place. That is what makes one a strict subset of the other rather than a fork. Research 004's most important finding becomes a format constraint rather than a footnote: the routable segment must use RFC 5737 documentation space, because the mesh decides public versus private by matching the address, and a private range there makes the hub test as unreachable while the mesh silently never forms. A segment without behind: is routable, and a non-documentation address in it should be refused before anything is raised — ADR 0008 applied to a configuration file, since the failure it prevents has no error at all. Four things left open, including the one that matters most: a lab machine is always privileged, so the user and edge profiles have no scenario that exercises them.
88 lines
4.7 KiB
Markdown
88 lines
4.7 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-23
|
|
deciders: jochen
|
|
reconstructed: false
|
|
---
|
|
|
|
# 31. The lab provides the underlay; the mesh builds the overlay
|
|
|
|
## Context
|
|
|
|
[Research 004](../01-RESEARCH/004-lab-network/analysis.md) worked out the topology a lab has to
|
|
reproduce: a routable segment using documentation addresses, a household segment behind NAT, a
|
|
router that forwards exactly one port so a *published-but-NATed* node is real, and a machine
|
|
that can attach to either segment or detach entirely.
|
|
|
|
It also records what makes that topology **mean** something, and this is where a boundary has
|
|
to be drawn. Hub election is by convention rather than by flag — the hub is the node whose
|
|
profile is server and whose overlay address begins `10.10.0.1`. Direct peering depends on two
|
|
nodes sharing a site. Names resolve from mesh configuration on each node.
|
|
|
|
Those are all facts the *mesh* establishes. The question is whether a scenario declares them.
|
|
|
|
It is tempting to say yes, because a scenario that hands you a working overlay is a scenario
|
|
you can start testing against immediately.
|
|
|
|
## Considered options
|
|
|
|
1. **The lab configures the overlay too** — assign the overlay addresses, elect the hub, write
|
|
the peer configuration, seed the names. Rejected, and the reason is the whole point of the
|
|
lab: **a lab that builds the overlay certifies its own work.** If the mesh's peering logic
|
|
is broken, a scenario that pre-built the peering still comes up green. The most valuable
|
|
thing the lab can test is precisely the part this would replace.
|
|
2. **The lab provides nothing but bare machines** — no addressing, no segments, no NAT. Also
|
|
rejected. Then the scenario cannot reproduce *published but behind NAT*, which research 004
|
|
identifies as the case that only exists in production today, and the lab loses its reason to
|
|
use virtual machines at all.
|
|
3. **The lab provides the underlay; the mesh builds the overlay.** Chosen.
|
|
|
|
## Decision
|
|
|
|
**A scenario declares the underlay** — the facts a machine would have before any of our
|
|
software touched it:
|
|
|
|
- which segments exist, and their address ranges
|
|
- which machine sits on which segment, at which address
|
|
- what NAT sits between them, and which ports are forwarded through it
|
|
- which machines are detached, and can be attached or detached during a run
|
|
|
|
**A scenario declares nothing about the overlay** — no overlay addresses, no hub, no peering,
|
|
no names, no certificates. Those are the mesh's job, and a scenario that supplied them would be
|
|
testing itself.
|
|
|
|
The rule stated in one line: **a scenario provides what a hosting provider and a home router
|
|
would provide, and nothing our software is responsible for.**
|
|
|
|
## Consequences
|
|
|
|
- **The overlay becomes a thing under test rather than a fixture.** Whether peers form,
|
|
whether the hub is elected, whether a NATed node's endpoint is learned — all of it is
|
|
observed rather than arranged. That is the class of fault research 004 says is discoverable
|
|
only in production today.
|
|
- The lab stays small, and stays honest. It needs to know about virtualisation, bridges,
|
|
addresses and NAT. It never needs to know what a mesh node is.
|
|
- A scenario cannot assert "the overlay came up" as a precondition, because it is an outcome.
|
|
A bootstrap scenario that wants a working overlay has to wait for one and check, which is
|
|
the correct shape.
|
|
- **The address ranges are load-bearing, not cosmetic.** The routable segment uses RFC 5737
|
|
documentation space specifically because the mesh's own code decides *public versus private*
|
|
by matching the address — a private range there makes the hub test as unreachable, and the
|
|
mesh silently never forms. Research 004 calls this the single most important fact in the
|
|
document, and the declaration format has to make getting it wrong hard.
|
|
- The router is a machine the lab materialises without being asked, because NAT requires
|
|
somewhere to run. That is an implicit machine in an otherwise explicit declaration, and it is
|
|
worth knowing about rather than discovering.
|
|
- **Host capability profiles are detected, not declared** — a consequence of
|
|
[research 006](../01-RESEARCH/006-mesh-from-scratch/code-skeleton.md), and consistent here: a
|
|
scenario does not say what a machine is allowed to do, it provides a machine. Which leaves an
|
|
open question: a lab machine is always privileged, so the `user` and `edge` profiles have no
|
|
scenario that exercises them yet.
|
|
|
|
## References
|
|
|
|
- [Research 004](../01-RESEARCH/004-lab-network/analysis.md) — the topology, the documentation
|
|
ranges, and the hub-election and peering conventions this deliberately does not touch.
|
|
- [ADR 0029](0029-the-labs-first-scenario-has-no-pipeline.md) — the two scenario classes this
|
|
declaration has to serve without forking.
|