jschoubben
122680b554
novox/hq 04-ISSUES/023. A consumer was given its password, the address,
the port and where its credential lives, and still could not connect —
the user name was invented by the provisioner and recorded nowhere, and
the rest sat in a JSON binding that a program reading KEY=value cannot
use.
Both halves have the same cause: the mesh knew something and did not say
it.
**Who a consumer is, said once.** The provisioner used to derive
mesh_<node>_<module> and that string existed nowhere else — not in the
control plane, not in the binding, and above all not at the consumer,
which has to present it. Now the mesh derives it once and sends it to
both ends, so they agree by construction rather than by two conventions
that were the same on the day they were written. The provisioners refuse
to invent one if the mesh says nothing, because falling back to a name
of their own would create a role the consumer would never guess and
everything would report success.
**Bound values reach the file that needs them.** ${bound:provision:key}
is the symmetric twin of the sealed placeholder, and simpler: these
values are not secret, so the control plane fills them in before sending
and the host gains no field and learns no format. It stays
name-agnostic — at, as and from are true of any provision, and every
other key comes from what the provider said it serves.
The asymmetry it removes was backwards. The secret is the hard case,
because the mesh must not be able to read it, and the secret was the
part that already arrived.
Keycloak and Gitea now produce complete connections, asserted from the
manifests on disk rather than from fixtures: every part filled, no
placeholder surviving as a value, and the password still a hole only the
host can close. Three faults injected, each caught.
Example modules
Manifests, not programs. They are here because the contract is easier to read as something that works than as a description of something that would.
Third-party software runs on the mesh, not of it (novox/hq ADR 0001). dnsmasq is not the mesh's, and neither is systemd-resolved — what is the mesh's is the fact only it can know, which is which machines exist and where they are. So the mesh writes that to a file and these read it.
Resolving a service named under a machine
postgres.novox.internal, plex.ace.internal. The first label is the service and the rest is the
node, so anything under a node's name must resolve to that node and a proxy there routes by
the name it was asked for. That routing is a separate concern and stays separate.
Two roles, and they are genuinely different things:
| claims | ||
|---|---|---|
| serving | the-dns-port |
answers the wildcards — dnsmasq.json |
| asking | the-resolver-configuration |
decides what the machine asks — resolved-split-dns.json, resolv-conf.json |
systemd-resolved cannot serve a wildcard, so it is only ever an asking module: it routes the mesh's suffix to something that can. Treating the two roles as one would produce a module that cannot work, which is the mistake worth naming.
Assign one of each. Two of either is refused by the mesh rather than fought over on the machine:
resolved-split-dns and resolv-conf both claim "the-resolver-configuration", and only one thing may hold it per node
ADR 0009's table names that resource /etc/resolv.conf, which is what it is, the way it writes
the seat. A claim is a name in the catalogue's own form, so it is written as one.
Why neither needs to know the machine's address
Both would ordinarily need it — a resolver must bind somewhere, and a stub must be pointed somewhere — and a static manifest cannot know it.
Neither does, because both name things the mesh itself named: the private network's interface
is mesh0 on every machine, and the address a resolver listens on for the machine's own use is
127.0.0.54 on every machine. A name the mesh chose is a name a manifest can use.
Asking for a bucket
object-store.json provides one, photos.json asks for one. Together they are the whole of an
edge, and they are here as a pair because that is the only way to see the halves line up:
| the provider says | the consumer says |
|---|---|
provides: s3-bucket |
requires: s3-bucket |
receives — where to be told who asked |
contributes: {bucket: photos} — what it wants |
grants — where their credentials land |
secrets — where to be given its key |
serves — port, scheme, region |
binds — where to be told all that |
The mesh adds the half neither can know: which machine the provider is on, and where it is on the private network. Neither manifest names an address, and that is what lets the same pair work on any mesh.
s3-bucket names the protocol, not the product (novox/hq ADR 0027). A
consumer's code is written against the S3 API, and swapping one store for another does not break
it — so the coupling is to S3. A database is the other case: an application is written against
PostgreSQL or against SQL Server, so those provisions name the engine.
What the pair is checked for. That the names match, that each side says where it wants to be
told, and that the consumer contributes the key the provisioner actually reads — bucket, not
name. Contributing name (which is what a database consumer contributes) resolves perfectly and
then fails on the machine with asked for a bucket and did not name it, which is a long way from
the manifest that caused it.
The provisioner that makes the credential true lives in
../objectstore-provisioner, and is proven against a real store in
the lab — including the assertion a database does not need, that a consumer cannot reach another
consumer's bucket. One store holds every bucket behind one endpoint, so that isolation is a
policy somebody wrote rather than a boundary the product has.