vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

add swarm-metrics, an agent CLI for the metrics store

Browse source 
swarm-metrics reads the swarm's VictoriaMetrics from inside an agent
container: query, query-range, series, labels and label-values, each one
GET against the store's Prometheus read API through the gateway, printing
the store's JSON. It authenticates the way swarm-logs does, with the
agent's own queue secret read from bao under the agent's leaf, sent as
a swarm-agent bearer.

On the metrics store's host the read API's auth map gains an agent arm
ahead of the Grafana one. It routes to swarm-metrics-agent-auth, a
swarm-logs-auth instance logged in under the existing swarm-metrics-auth
leaf, whose bao grant now includes swarm/agents/+/queue read. The check is
rate-limited per address like the log store's
(deploy.victoriametrics.agentAuth{Rate,Burst,VerdictTtl}).

nix/agent-modules/metrics.nix installs the wrapped binary when the hive
forwards HIVE_AGENT_METRICS_URL (from swarm.victoriametrics.domain) and a
store address, the same gate as swarm-logs. Adds the base:swarm-metrics
skill and the CLI reference with its freshness check.

Fixes #5395
This commit is contained in:
atlas 2026-10-17 00:55:46 +02:00 • committed by mara
commit e92f118bda
30 changed files with 1417 additions and 88 deletions
Download patch file Download diff file Expand all files Collapse all files

60
swarm-metrics/README.md Normal file
View file

@ -0,0 +1,60 @@
# swarm-metrics
An agent's CLI for the swarm metrics store (VictoriaMetrics), the sibling of
`swarm-logs`. Each verb is one read against the store's Prometheus-compatible
API through the gateway, and prints the store's JSON answer unchanged, for
`jq`.
| verb | store endpoint | for |
| -------------- | ----------------------------- | --------------------------------------- |
| `query` | `/api/v1/query` | a MetricsQL expression at one instant |
| `query-range` | `/api/v1/query_range` | the same over a window; needs `--start` |
| `series` | `/api/v1/series` | which series match a selector |
| `labels` | `/api/v1/labels` | label names |
| `label-values` | `/api/v1/label/<name>/values` | one label's values (`__name__`: names) |
Read-only: nothing here writes, and the gateway serves no write path to this
caller.
## ⚠️ No scoping
The gateway forwards the request unmodified, so any authenticated caller reads
the whole swarm's metrics, every hive's.
## How it authenticates
As the agent itself, exactly as `swarm-logs` does: on each request it reads
the agent's own queue secret, `swarm/agents/<agent>/queue`, from the swarm
secret store with the agent's store certificate, and sends
`Authorization: Bearer swarm-agent.<agent>.<secret>`. A 401 makes it read the
secret again and retry once.
On the metrics store's host, nginx hands a bearer of that shape to
`swarm-metrics-agent-auth`, a `swarm-logs-auth` instance logged in to the
store under that host's `swarm-metrics-auth` leaf. It grants a secret it has
verified for 60 s by default (`deploy.victoriametrics.agentAuthVerdictTtl`).
A 403 is the gateway's per-address rate limit on these checks, and
`swarm-metrics` doesn't retry it.
🩸 The secret is never logged or rendered into an error.
## Configuration
Supplied by `nix/agent-modules/metrics.nix`, which wraps the binary.
| variable | what |
| ------------------------ | ------------------------------------------------ |
| `HIVE_AGENT_METRICS_URL` | the metrics store's gateway origin |
| `HIVE_AGENT_NAME` | this agent's name; the store path and role |
| `BAO_ADDR` | the secret store's address |
| `BAO_CLIENT_CERT` | path of the agent's live store certificate |
| `BAO_CLIENT_KEY` | path of its key |
| `BAO_CACERT` | path of the store's CA; missing or empty is fine |
With no `HIVE_AGENT_METRICS_URL` the binary says there is no metrics store;
with the URL and no store address it reports a deployment bug by name.
## Output
The store's response body, unmodified, newline-terminated. A non-2xx exits
non-zero with its status and body on stderr, never as an empty result.