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(#3265): the swarm metrics pair, and what an operator turns on

Browse source
This commit is contained in:
atlas 2026-08-16 21:41:52 +02:00 • committed by mara
commit f6870c6a85
1 changed files with 34 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/swarm/services.md
View file

@ -61,3 +61,37 @@ See [`sso.md`](sso.md) for bootstrapping the first user and the OIDC
relying-party flow, and [`secrets.md`](secrets.md) for where each of
authelia's keys is generated and read.
### Metrics (VictoriaMetrics + Grafana)
The swarm's telemetry lands in one VictoriaMetrics and is read through
one Grafana, in two containers at `metrics.<swarm-domain>` and
`grafana.<swarm-domain>`. Two containers rather than one so Grafana can
be restarted or broken without taking the time-series database with it.
Both are **opt-in** — unlike authelia and matrix they do not follow
`swarm.enableRequiredServices`, because turning them on starts a
database that grows for as long as the swarm runs:
```nix
services.hyperhive.swarm.victoriametrics.enable = true;
services.hyperhive.swarm.grafana.enable = true;
```
| Option | When you'd touch it |
|---|---|
| `swarm.victoriametrics.retentionPeriod` | Default `5y`. Lower it once you have measured how fast this swarm actually fills a disk — the default is deliberately generous because too-short silently discards history you cannot get back. |
| `swarm.grafana.oidc.role` | Default `Admin` for everyone who logs in. Lower to `Viewer`/`Editor` if the swarm grows operators who should not be able to reconfigure Grafana. |
| `swarm.grafana.datasourceUrl` | Only if you front VictoriaMetrics with something else. It defaults to the store on this host, which is the only thing it can reach. |
**Logging in.** Grafana is behind swarm SSO, so the accounts are the
authelia ones — there is no separate Grafana password, and the local
login form is switched off whenever SSO is configured. If you enable
Grafana on a host with no authelia, the form stays on and Grafana's
default `admin`/`admin` applies; change it before exposing that host.
The metrics **arrive** from the swarm's OTEL collector, not from agents
directly — see [`../observability.md`](../observability.md). Neither
container is reachable except through the gateway: both bind loopback,
and VictoriaMetrics' write endpoint takes no credential, so the
collector is the only intended writer.