vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

nix: comments state current behaviour, not history

Browse source 
Rewrite comments and option descriptions under nix/ that narrate how the
code got here ("used to", "new name", "sat at the TOP", "no longer",
renamed/moved narration, attributions) to say what the code does now and
why. Comments and description strings only; no logic changes.

Files in open PR #4970's diff are left alone. Refs #3902
This commit is contained in:
atlas 2026-10-05 02:34:39 +02:00
commit 1c90619fbb
45 changed files with 331 additions and 411 deletions
Download patch file Download diff file Expand all files Collapse all files

111
nix/host-modules/swarm-bao.nix
View file

@ -760,22 +760,22 @@ let
}
'';
# ── the principals that used to share the hive's own leaf ──────────────────
# ── the principals that each hold a leaf of their own ──────────────────────
#
# 🩸 Each of these reads exactly ONE path in the store, and until this split
# each did it holding `deploy.bao.clientCertFile` — the hive's own leaf,
# whose policy (`swarm-secret-client`'s `policy::render`) granted read on
# `swarm/agents/*`, `swarm/hives/<hive>/*` AND `swarm/services/*`. Principals
# presenting one certificate are ONE principal to bao, so the union of what
# they need was the only grant expressible: the unit that fetches Grafana's
# OIDC client secret could fetch every agent credential in the swarm, and the
# unit that fetches this hive's queue credential could fetch Grafana's. Least
# privilege was not misconfigured, it was unrepresentable.
# 🩸 Each of these reads exactly ONE path in the store, and does it holding
# its own leaf rather than `deploy.bao.clientCertFile` — the hive's own leaf,
# whose policy (`swarm-secret-client`'s `policy::render`) grants read on
# `swarm/agents/*`, `swarm/hives/<hive>/*` AND `swarm/services/*`.
# Principals presenting one certificate are ONE principal to bao, so sharing
# the hive's leaf would leave only the union of what they need expressible:
# the unit that fetches Grafana's OIDC client secret could fetch every agent
# credential in the swarm, and the unit that fetches this hive's queue
# credential could fetch Grafana's.
#
# Each now gets its own leaf, its own cert-auth role and a policy holding the
# one `secret/data/…` path that principal's script actually names — spelled to
# the LEAF rather than to a prefix, for the reason `matrixCtlPolicyText` above
# gives for doing the same.
# Each gets its own leaf, its own cert-auth role and a policy holding the
# one `secret/data/…` path that principal's script actually names — spelled
# to the LEAF rather than to a prefix, for the reason `matrixCtlPolicyText`
# above gives for doing the same.
#
# ⚠️ The queue-credential reader is PER HIVE and the OIDC readers are not,
# and that asymmetry is the shape of the paths rather than a preference. A
@ -784,7 +784,7 @@ let
# `swarm/services/<client-id>/` and a swarm registers each of those exactly
# once. A single role for a per-hive reader would have to name `hives/*` to
# serve every hive — which would let one hive read another's queue
# credential.
# credential, a reach no hive needs.
readStanza = path: ''
path "${path}" {
capabilities = ["read"]
@ -1024,10 +1024,9 @@ let
# `tls_require_and_verify_client_cert` on the API listener to scrape THAT
# instead, would each trade that property away for nothing.
#
# Unconditional, and that is the change this carries: the reader is now the
# collector in this very container (below), which renders wherever the store
# does. There is no longer a host where this endpoint has no reader, so there
# is nothing left for it to be a function of.
# Unconditional: the reader is the collector in this very container (below),
# which renders wherever the store does. There is no host where this
# endpoint has no reader, so it is not a function of anything.
metricsListener = {
metrics = {
type = "tcp";
@ -1104,22 +1103,18 @@ let
'';
# ⚠️ Neither the listener above nor the forwarder below has a condition of
# its own, and they lost theirs for the same reason at different times.
# its own.
#
# The listener used to be gated on `scrapeHere = deployCfg.swarm-otel.enable`
# — "does the swarm's collector happen to run on THIS host" — because the
# thing reading it was that collector, over loopback, which only works when
# the two land together. mara's ruling (*"move the existing scraper
# to the local collector"*) removes the premise rather than the symptom: the
# scraper is now in this container, so the reader is wherever the store is,
# and the metrics path stops being silently dead on every host that does not
# also run swarm-otel.
# The listener's reader is the collector in this container, which sits
# wherever the store does. "Does the swarm's collector run on THIS host" is
# not a question it depends on: gating it on that would leave the metrics
# path silently dead on every host that does not also run swarm-otel.
#
# The forwarder never had a defensible one. "Does the swarm have a collector"
# is not a question that can be false (mara: "the swarm always has at least
# one instance of all the swarm level services"), so both earlier gates —
# `otel.enable`, then `deploy.swarm-otel.enable` — asked about the wrong host
# and rendered no forwarder wherever the answer happened to be no.
# "Does the swarm have a collector" is not a question that can be false —
# the swarm always has at least one instance of all the swarm level
# services — so gating the forwarder on `otel.enable` or
# `deploy.swarm-otel.enable` would ask about the wrong host and render no
# forwarder wherever the answer happened to be no.
#
# The only condition that belongs on either is the one already enclosing this
# block: the store is deployed on this host.
@ -2133,14 +2128,13 @@ in
# granter step, on the host where that step runs.
environment.etc."hyperhive/bao-bootstrap-policy.hcl".source = ./bao-bootstrap-policy.hcl;
# 🚫 No `swarm.otel.scrapeTargets.bao` entry any more, and its absence is
# the deliverable rather than a tidy-up. That option is read only by the
# SWARM collector, over loopback, so declaring the store there meant its
# metrics existed exactly on the hosts that also ran swarm-otel and
# nowhere else — silently, since a store with no entry looks identical to
# one nothing scrapes. The scrape moved into this container's own
# collector (see `receivers.prometheus` below), which travels with the
# container's own collector is confirmed.
# 🚫 No `swarm.otel.scrapeTargets.bao` entry, and its absence is
# deliberate. That option is read only by the SWARM collector, over
# loopback, so a store declared there would have metrics exactly on the
# hosts that also run swarm-otel and nowhere else — silently, since a
# store with no entry looks identical to one nothing scrapes. The scrape
# runs in this container's own collector (see `receivers.prometheus`
# below), which travels with the store.
# ⚠️ The one nginx exception to this file's header, and it is one because
# it never terminates. `ssl_preread` reads the SNI off the ClientHello
@ -2898,11 +2892,11 @@ in
'';
};
# 🩸 The principals that used to log in as the hive. See the block around
# `perHiveReaders` for what each grant is and why the first is per hive;
# the units are identical apart from the objects they
# write, so the shape lives in `readerPolicyUnit` and the difference is
# visible here in one line each.
# 🩸 The principals that each log in with a leaf of their own, not as the
# hive. See the block around `perHiveReaders` for what each grant is and
# why the first is per hive; the units are identical apart from the
# objects they write, so the shape lives in `readerPolicyUnit` and the
# difference is visible here in one line each.
systemd.services.swarm-bao-queue-agent-policy = readerPolicyUnit "write the per-hive queue-credential bao policies and cert-auth roles" queueAgentReaders;
systemd.services.swarm-bao-grafana-oidc-policy = readerPolicyUnit "write Grafana's OIDC-secret-reader bao policy and cert-auth role" grafanaOidcReaders;
@ -3701,31 +3695,26 @@ in
# this line leaves a collector that validates, starts,
# reports healthy and forwards nothing.
directory = "/var/log/journal";
# ⚠️ `--merge` stays from when this journal was host-linked
# and `journalctl --follow` (unqualified) found no entry for
# the current boot under that tree, crash-looping the
# receiver every ~2s with "No journal boot entry found for
# the specified boot (+0)". The journal is local now, so the
# current boot has an entry here too — kept rather than
# dropped so the first deploy changes exactly one thing;
# revisit once delivery is confirmed.
# ⚠️ `--merge` is a guard: an unqualified
# `journalctl --follow` over a journal with no entry for the
# current boot (a host-linked one) crash-loops the receiver
# every ~2s with "No journal boot entry found for the
# specified boot (+0)". This journal is container-local, so
# the current boot has an entry and the flag changes nothing.
merge = true;
storage = "file_storage";
};
# The scrape that used to belong to the swarm collector, now
# one hop shorter and one host less fussy — mara:
# *"move the existing scraper to the local collector"*.
# The store's scrape, run by this container's own collector.
#
# ⚠️ `metrics_path` and `params` are STATED, and both have to
# be: openbao serves no `/metrics` at all, and
# `/v1/sys/metrics` answers JSON unless the format is asked
# for. A scrape of the default path 404s and a scrape without
# the query parses as nothing — each reads as a dead exporter
# rather than as a wrong request, which is how the previous
# owner of this scrape learned to spell it
# (./swarm-otel.nix's `loopbackScrapeConfig`, still the
# renderer for every other service's target).
# rather than as a wrong request. The spelling matches
# ./swarm-otel.nix's `loopbackScrapeConfig`, the renderer for
# every other service's target.
#
# No credential, unlike the swarm collector's
# `publishedScrapeTargets` jobs: the target is the loopback