From c028b2ecfc216490419c9c5c277061fb0442049a Mon Sep 17 00:00:00 2001 From: atlas Date: Sat, 15 Aug 2026 22:50:51 +0200 Subject: [PATCH] docs(swarm): say how to make a hive report, not that nothing does The section carried a "nothing publishes yet" note that is now false, and said nothing about the one thing an operator has to do. Written to the reader's question rather than the author's: what to set, what defaults on an all-in-one host, what has to be carried by hand to a hive that is not the swarm host, and where to look when a hive goes quiet. The identity and the publish cadence are stated because they constrain the staleness threshold an operator picks; the mechanism behind them is not. --- docs/swarm/README.md | 39 ++++++++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 748478b7..14499b37 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -294,9 +294,9 @@ it said. Hives publish upward through the swarm queue; the controller never reaches down to collect, so a hive that cannot reach the swarm still knows its own state — you just cannot see it from here. -⚠️ **Nothing publishes yet.** The read path is in place; the hive-side -publisher lands in a later change. Until it does, every hive reads -`never_reported`. +A hive publishes only once it has been given the three +`swarm.statusPublish` coordinates below. A hive that has not reads +`never_reported` — it is not broken, it just has nothing to say upward. | freshness | what to do about it | |---|---| @@ -311,8 +311,37 @@ arrival, not one the hive put in its own payload. Set `services.hyperhive.swarm.controller.staleAfterSeconds` (default `120`) **above the rate hives publish at**, or everything reads `stale` -between reports. It takes effect on the next request; nothing has to -re-publish. +between reports. Hives publish once a minute, so the default tolerates +one missed report and flags two. It takes effect on the next request; +nothing has to re-publish. + +### Making a hive report (`swarm.statusPublish`) + +Three options, on the **hive**, set together or not at all — a +half-configured hive is an eval error rather than one that quietly never +reports: + +| option | what to set it to | +|---|---| +| `natsUrl` | where the swarm queue listens, as this hive reaches it | +| `tokenEndpoint` | the swarm IdP's `/api/oidc/token` | +| `clientSecretFile` | path to this hive's client secret, plaintext | + +On a host that runs the queue and the IdP itself, all three default to +the local ones and there is nothing to set. Any other hive needs them +spelled out, and needs the secret to physically be there: the swarm does +not distribute it. Copy `hive-.secret` out of the swarm host's +`swarm.authelia.hostClientSecretDir` with whatever secret management the +deployment already uses. + +The identity is not a choice — a hive authenticates as `hive-` +and publishes under `hiveName`, the same name that keys `swarm.hives`. + +If a hive stops reporting, its own dashboard is the place to look: a +failure to publish raises a warning banner there after three consecutive +misses. It stays `warn` rather than `crit` on purpose — a hive that +cannot reach the queue is not itself unhealthy, so it does not start +calling itself degraded for being unable to say it is fine. The endpoint answers **503** when this host has no swarm queue configured, or has one and cannot read it — deliberately not an empty