docs: clear write-good.Passive hits in swarm secrets/README docs
Part of #4548 — third batch. This PR: docs/swarm/secrets.md (16 hits), docs/swarm/README.md (15 hits) = 31 more of the 353 (130 total across the three PRs so far). Same method as #4551/#4553: minimal, meaning-preserving active-voice rewrites, no restructuring beyond what each flagged sentence needed, no vale-off silencing. Genuine false positives left in place: predicate-adjective state descriptions ("is required" x4, "is enabled", "is disabled"), one systemd terminology reference ("is wanted (not required)" — literally naming systemd's Wants=/Requires= dependency-type distinction, not passive voice), and one design-intent idiom ("both are expected" — same shape as earlier docs-lint work).
This commit is contained in:
parent
18c5b5c5ad
commit
c985702bb0
2 changed files with 55 additions and 55 deletions
|
|
@ -18,7 +18,7 @@ build .#docs-swarm` / `.#docs-deploy` or the website's `/options/swarm.html`
|
|||
own `services.hyperhive.domain` DNS name and its own set of agent
|
||||
containers.
|
||||
- **swarm** — one or more hives whose operators have declared them
|
||||
as peers. Agents can be qualified as `agent@hive-domain`.
|
||||
as peers. You can qualify an agent as `agent@hive-domain`.
|
||||
- **peer hive** — any hive in `services.hyperhive.swarm.hives` other
|
||||
than this one. Peers are _derived_, not declared: the directory lists
|
||||
every hive including yourself, and `hiveName` says which one you are.
|
||||
|
|
@ -134,7 +134,7 @@ because `services.hyperhive.hiveName` says which entry is itself.
|
|||
Empty (the default) means this host isn't in a swarm. Once non-empty it
|
||||
**must** contain an entry for `hiveName`; eval fails naming the missing
|
||||
hive. That assertion is load-bearing rather than pedantic — "my peers"
|
||||
is derived as _everything that isn't me_, so a directory that doesn't
|
||||
comes from _everything that isn't me_, so a directory that doesn't
|
||||
contain you derives every hive as a peer and you peer with yourself.
|
||||
|
||||
`domain` defaults to `<name>.<swarm.domain>`, the convention every hive
|
||||
|
|
@ -161,7 +161,7 @@ addressed by something else.
|
|||
directory and serves it at `GET /api/hives`; `swarm-ui`'s overview
|
||||
page renders it (`docs/swarm/ui.md`). This is the operator-facing
|
||||
"what hives exist" surface — a per-hive dashboard "peer hives"
|
||||
display existed here once and was removed in favour of it.
|
||||
display existed here once; it no longer exists, in favour of this.
|
||||
|
||||
2. **Matrix federation** — when `matrix.enable` is on, tuwunel
|
||||
federates with the peer's matrix server (discovered via the peer's
|
||||
|
|
@ -170,12 +170,12 @@ addressed by something else.
|
|||
**container's** trust bundle, independent of this directory.
|
||||
|
||||
⚠️ **That container currently trusts no swarm-internal CA**, so a
|
||||
self-signed gateway certificate doesn't federate. The swarm root
|
||||
can't be listed there: `security.pki.certificateFiles` is
|
||||
self-signed gateway certificate doesn't federate. You can't list the
|
||||
swarm root there: `security.pki.certificateFiles` is
|
||||
read when the system is _built_, and the root is a runtime file (its
|
||||
key must never enter the store), so there is no build-time name for
|
||||
it. Bridging that needs a runtime mechanism and is tracked as its own
|
||||
issue. Until then, federation needs CA-issued certs (ACME). See
|
||||
it. Bridging that needs a runtime mechanism; a separate issue tracks
|
||||
it. Until then, federation needs CA-issued certs (ACME). See
|
||||
`docs/integrations/matrix.md` for federation firewall + TLS requirements.
|
||||
|
||||
3. **WireGuard mesh** (optional) — `deploy.wireguard.enable` reads each
|
||||
|
|
@ -281,7 +281,7 @@ is required. Out of scope for v0.
|
|||
|
||||
## Snapshot store
|
||||
|
||||
One further option lives in this namespace but is documented with the
|
||||
One further option lives in this namespace but its docs live with the
|
||||
service it points at: `services.hyperhive.swarm.snapshotStore.{address,
|
||||
port}` tells this hive where the swarm's `btrfs receive` endpoint is, so
|
||||
`hivectl agent <name> subvol snapshot push` has somewhere to stream to.
|
||||
|
|
@ -296,8 +296,8 @@ migrating agent keeps one unbroken incremental chain. See
|
|||
`services.hyperhive.deploy.swarm-controller.enable` runs the `swarm-controller`
|
||||
daemon on this host. **Off by default and deliberately not derived from
|
||||
`services.hyperhive.enable`**: a swarm has one controller, so enabling it
|
||||
is a statement about swarm topology, not about whether hyperhive is
|
||||
installed. Every hive runs `hive-c0re` (the agents on that host); one
|
||||
is a statement about swarm topology, not about whether the operator has
|
||||
installed hyperhive. Every hive runs `hive-c0re` (the agents on that host); one
|
||||
hive additionally runs this (what's true across hives).
|
||||
|
||||
What it serves, why it's a unix socket rather than a port, and the
|
||||
|
|
@ -380,8 +380,8 @@ with the credential itself and aren't configurable.
|
|||
|
||||
On a host that runs the queue, `agentNatsUrl` defaults to
|
||||
`nats://<network.bridgeIp>:<swarm.nats.port>`, which is the only address that
|
||||
works from inside a container: the port is opened on the bridge interface and
|
||||
nowhere else. ⚠️ **Never a loopback address here** — the hive's own
|
||||
works from inside a container: the firewall opens the port on the bridge
|
||||
interface and nowhere else. ⚠️ **Never a loopback address here** — the hive's own
|
||||
`statusPublish.natsUrl` is loopback and correct, because `hive-c0re` shares the
|
||||
host's network namespace. An agent doesn't, so `127.0.0.1` reaches the agent.
|
||||
|
||||
|
|
@ -391,7 +391,7 @@ above, plus `HIVE_AGENT_OIDC_CLIENT_SECRET_FILE` and
|
|||
`HIVE_AGENT_OIDC_CLIENT_ID_FILE`, which point into the unit's own credentials
|
||||
directory. The last two come from the delivered credential rather than from
|
||||
config — see [`secrets.md`](secrets.md#hive-level--one-of-each-per-hive) for
|
||||
how it gets there. A hive that hasn't been given the queue's address for its
|
||||
how it gets there. A hive lacking the queue's address for its
|
||||
agents sets none of the four and each agent logs that it has none; a half-set
|
||||
environment logs an error and the harness keeps serving.
|
||||
|
||||
|
|
@ -404,10 +404,10 @@ agent talks about itself here and reads nothing. Rows aren't retained — a
|
|||
subscriber that wasn't listening missed them, the same as on the agent's own
|
||||
live stream.
|
||||
|
||||
A row too large for the queue's `max_payload` would be refused outright and
|
||||
The queue would refuse a row too large for its `max_payload` outright and
|
||||
take the connection down with it, so the harness drops such a row's body before
|
||||
sending and leaves a marker in its place; the summary, level and icon still
|
||||
arrive. A row that's too large even without its body is logged and skipped.
|
||||
arrive. The harness logs and skips a row that's too large even without its body.
|
||||
|
||||
The second thing an agent publishes is its **turn-state header**, on
|
||||
`$SWARM.agent-state.<hive>.<agent>` — same shape of subject, same grant
|
||||
|
|
|
|||
Loading…
Reference in a new issue