From 7b226f21dd8dff776225d14bc732ccc753200220 Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 2 Oct 2026 09:30:43 +0200 Subject: [PATCH] docs(swarm): state behaviour instead of denying absent options --- docs/swarm/README.md | 14 ++++++-------- docs/swarm/services.md | 7 ++----- swarmctl/README.md | 3 +-- 3 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 3b6c913d..7ace9665 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -46,10 +46,9 @@ identity, forge user, config repo, store identity and matrix account, then sends the hive a deploy message. A new agent starts `paused`. `services.hyperhive.deploy.swarm-controller.enable` runs it on this host; -`singleHostSwarm` turns it on. **Otherwise off by default and deliberately -not derived from `deploy.hive-controller.enable`**: a swarm has one -controller, so enabling it states a fact about swarm topology, not about -whether this host runs a hive. +`singleHostSwarm` turns it on. **Otherwise off: set it on the one host that +runs the controller.** A swarm has one controller, so enabling it states a +fact about swarm topology, not about whether this host runs a hive. What it serves, why it's a unix socket rather than a port, and the socket-directory constraint that governs where `socketPath` may point: @@ -254,10 +253,9 @@ re-derive. Approval happens once, at the swarm level: a hive receives a decision, not an event to adjudicate. **`internal/knowledge` is on that path.** The controller's is the only -hook on it; hives register none of their own -([`knowledge.md`](../integrations/knowledge.md) covers clearing a leftover). -A webhook has exactly one target URL, so a second registration would take -delivery away from the first rather than add a recipient. +hook on it ([`knowledge.md`](../integrations/knowledge.md) covers clearing a +leftover). A webhook has exactly one target URL, so a second registration +would take delivery away from the first rather than add a recipient. diff --git a/docs/swarm/services.md b/docs/swarm/services.md index 3c1fd084..01a7da65 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -26,8 +26,7 @@ host's `/etc/hosts` entries for the names it serves (`gateway.localHostsEntry`), the queue's auth-callout keys (`deploy.nats.autoGenerateCallout`) and where the secret store's bootstrap token goes (`deploy.bao.bootstrapTokenFile`). You can still set each derived -toggle on its own, which wins, so "all local except X" needs no further -option. +toggle on its own, and that setting wins. **Both default to off**, and that's deliberate: a host can't tell whether it's meant to be the swarm's service host, so this is an @@ -210,9 +209,7 @@ gateway either way. **Both store exporters are unconditional**, and `deploy.victoriametrics.enable` doesn't gate them: that option says this host _runs_ the store, while the swarm -has one either way, reached by its swarm name through the gateway. A collector -with no exporter would receive from every hive and drop it silently, because an -absent exporter isn't an error. +has one either way, reached by its swarm name through the gateway. Agent-side configuration, and what a hive's own collector does, are in [`../scheduler/observability.md`](../scheduler/observability.md). diff --git a/swarmctl/README.md b/swarmctl/README.md index ca97da99..4771c024 100644 --- a/swarmctl/README.md +++ b/swarmctl/README.md @@ -32,8 +32,7 @@ that. ## One file, two writers `swarmctl` reads and writes `users.yml` — authelia's own users database — -directly, with no second store. `swarm-authelia-bridge` writes agent -subjects into the same file. +directly. `swarm-authelia-bridge` writes agent subjects into the same file. ⚠️ The file is round-tripped, so **comments and hand-formatting do not survive a write**. Values do, and so do keys this binary does not model.