docs: trim the trustBundle comment under the 30-line lint
Keeps the three constraints a reader cannot derive; the reasoning behind them lives in the PR.
This commit is contained in:
parent
cb650f2dbb
commit
e7a5e93bbc
1 changed files with 16 additions and 37 deletions
|
|
@ -63,46 +63,25 @@ in
|
|||
requires = [ "hive-tls-ca.service" ];
|
||||
};
|
||||
|
||||
# Assemble system CAs + the hive CA into one bundle, for runtimes whose
|
||||
# trust variable *replaces* the default store (Go's `SSL_CERT_FILE`,
|
||||
# rustls-native-certs) rather than adding to it — pointing those at
|
||||
# `caContainerPath` alone would drop every public anchor.
|
||||
# System CAs + hive CA in one bundle, with `SSL_CERT_FILE` set on each
|
||||
# consumer — for runtimes whose trust variable *replaces* the store (Go,
|
||||
# rustls-native-certs). An additive one (Node's `NODE_EXTRA_CA_CERTS`,
|
||||
# hive-ci) needs no bundle and should not use this.
|
||||
#
|
||||
# The header above says consumption stays at the call site, and the *env
|
||||
# var* still does. The assembly does not: four containers were each
|
||||
# hand-rolling this concat, which is how they came to share one defect —
|
||||
# `wantedBy` + `before` express ordering but not success, so a failed
|
||||
# assembly let the consumer start against a missing file and end up
|
||||
# trusting **nothing**, which fails every outbound TLS call while the unit
|
||||
# looks healthy.
|
||||
# imports = [ (caTrust.trustBundle { inherit pkgs; name = "swarm-nats";
|
||||
# consumers = [ "swarm-nats-auth" ]; }) ];
|
||||
#
|
||||
# Two things this does that a hand-rolled version kept getting wrong:
|
||||
# - `requires` on the CONSUMER, so a failed bundle stops it — and the
|
||||
# dependency is visible in `systemctl status <consumer>`, where someone
|
||||
# debugging a TLS failure actually looks.
|
||||
# - assemble to a temp path, check the result is non-empty and actually
|
||||
# contains a certificate, and only then move it into place. `cat` of an
|
||||
# empty bind exits 0, so `set -e` alone does not catch it, and a partial
|
||||
# bundle must never appear under the final name.
|
||||
# Three constraints, each earned:
|
||||
# - `requires` on the CONSUMER: `before` orders but does not gate, so a
|
||||
# failed assembly otherwise leaves it running and trusting *nothing*.
|
||||
# - assemble to a temp path, verify, then move: `cat` of an empty bind
|
||||
# exits 0, and a partial bundle must never appear under the final name.
|
||||
# - `consumers` are BARE unit names — they are `systemd.services` keys
|
||||
# (no suffix) *and* go in `before`/`requires` (suffixed). Reversed, the
|
||||
# edge names a unit that does not exist and systemd orders nothing.
|
||||
#
|
||||
# Returns a MODULE to import inside the container, not an attrset to splice
|
||||
# in — same shape as `swarm-container-resolver.nix`, and for a concrete
|
||||
# reason: a caller that already writes `systemd.services.<consumer> = …`
|
||||
# cannot also write `systemd.services = …` in the same attrset, so anything
|
||||
# returning bare services forces the call site to be restructured.
|
||||
#
|
||||
# imports = [ (caTrust.trustBundle { inherit pkgs; name = "swarm-nats"; consumers = [ "swarm-nats-auth" ]; }) ];
|
||||
#
|
||||
# It sets `SSL_CERT_FILE` on each consumer itself. That is the right default
|
||||
# for this helper's audience — runtimes whose trust variable *replaces* the
|
||||
# store. A runtime with an additive variable (Node's `NODE_EXTRA_CA_CERTS`,
|
||||
# hive-ci) needs no bundle at all and should not use this.
|
||||
#
|
||||
# `consumers` are BARE unit names (no `.service`): they are used both as
|
||||
# `systemd.services` attribute keys, which must not carry the suffix, and
|
||||
# inside `before`/`requires`, which must. Getting that backwards produces an
|
||||
# edge to a unit that does not exist — which systemd accepts in silence,
|
||||
# ordering nothing.
|
||||
# Returns a module, not bare services: a caller already writing
|
||||
# `systemd.services.<consumer>` cannot also write `systemd.services`.
|
||||
trustBundle =
|
||||
{
|
||||
name,
|
||||
|
|
|
|||
Loading…
Reference in a new issue