vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: authenticated telemetry ingest, and where the hive's secret comes from

Browse source 
Three readers, three different questions:

`observability.md` gets the operator's version — what to set (nothing, on an
all-local swarm), what to set elsewhere, what a misconfiguration looks like
(401s and a missing hive), and what turning it off actually costs.

`swarm/secrets.md` extends the existing client-secret row rather than adding
one, because this is a new *reader* of a secret already described. It notes the
one thing that makes this reader unusual: a host unit reads the file in place,
so unlike every other consumer there is no delivery step to get wrong.

`setup.md` gets one bullet under security notes, since a first-run hive gets
the property without doing anything and should know it has it.
This commit is contained in:
atlas 2026-08-19 15:06:15 +02:00 • committed by mara
commit 9dc60061e7
3 changed files with 45 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/observability.md
View file

@ -186,6 +186,38 @@ redefines it — the agent-facing value is *derived*
keeps working unchanged. The bridge port is contributed to `exposeHostPorts`
automatically; there is nothing to open by hand.
### Authenticated ingest
The swarm tier gives **each hive its own receiver**, and stamps the `hive` label
from whichever receiver accepted a sample. A hive therefore cannot report
metrics as another hive, and cannot relabel its own by editing what it sends —
the label is not taken from the payload at all.
**On an all-local swarm there is nothing to set.** Each hive already has an
identity, and its collector reads the secret that host's own authelia minted.
**On a hive that does not host the swarm's services**, the secret has to arrive
somehow — copy it across and name it:
```nix
services.hyperhive.otel.clientSecretFile = "/run/secrets/hive-telemetry.secret";
```
Getting that wrong shows up as the hive's collector logging 401s from the swarm
tier and no metrics appearing for that hive. When a single host runs both tiers
the build catches it instead, because it can see both sides.
To accept unauthenticated ingest — every writer on the swarm network already
trusted, or a swarm with no authelia:
```nix
services.hyperhive.swarm.otel.requireHiveIdentity = false;
```
⚠️ That reopens the original hole rather than merely skipping a check: while an
unauthenticated port is listening, anything that can reach the collector can
attribute metrics to any hive.
### `services.hyperhive.otel.collector.port` — port, default `4318`
The OTLP/HTTP port the hive tier listens on, bound to the bridge IP only. The