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(network): drop the otel reasoning instead of restating it

Browse source 
Review feedback from mara ("does the otel info even belong in there?") and
argus: `docs/observability.md` already states twice that the collector's
bridge port is contributed automatically and that neither line is needed for
hyperhive's own telemetry. A second copy of that reasoning in the option
description is a third place to drift from — and drift is what produced the
misleading example this PR started out fixing.

So remove the explanation rather than relocate it. With no otel content in
the option at all there is nothing to keep in sync, and observability.md
stays the one place that owns the otel-specific reasoning.

`example = [ 4318 ]` goes too: 4318 is the OTLP port, so the example still
pointed at otel without naming it.

Also fixes the same confusion one doc over, since it is this PR's subject:
observability.md's own "Network access" section used `otel.endpoint` as the
example for pointing something *else* at a host-local service, immediately
above a warning that you do not need it for otel. It now uses a generic port
and names the reason loopback is wrong from inside a container. While there,
the bridge is `hive-br0`, not `hvbr0` — the only occurrence in the tree.

Refs #3402
This commit is contained in:
atlas 2026-08-19 00:19:13 +02:00
commit fc3bd2a26c
2 changed files with 12 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/observability.md
View file

@ -208,26 +208,22 @@ a build error naming the reason rather than telemetry silently going nowhere.
## Network access
Agent containers can only reach the host on ports 80 and 443 by default. If
your OTLP collector runs on a non-standard port on the same host (e.g. a local
dev collector on `:4318`), open that port via:
Agent containers can only reach the host on ports 80 and 443 by default. To let
them reach some other host-local service you run yourself — a database, a
scratch HTTP endpoint — open its port on the bridge:
```nix
services.hyperhive.network.exposeHostPorts = [ 4318 ];
services.hyperhive.network.exposeHostPorts = [ 5432 ];
```
Then point the endpoint at the bridge IP rather than loopback:
and point whatever consumes it at `10.42.0.1:5432` rather than loopback: inside
a container, loopback is the *container*. The bridge IP is the host's address on
the `hive-br0` bridge. The service must also bind an address the bridge can
reach — a `127.0.0.1`-only listener stays unreachable no matter what the
firewall allows. See `docs/network.md::Reaching host services` for details.
```nix
services.hyperhive.otel.endpoint = "http://10.42.0.1:4318";
```
The bridge IP is the host's address on the `hvbr0` bridge, typically
`10.42.0.1`. See `docs/network.md::Reaching host services` for details.
⚠️ **You do not need either line for hyperhive's own telemetry** — `otel.enable`
contributes the collector's port and derives the endpoint itself. The above is
for pointing something *else* at a host-local service.
⚠️ **None of this is needed for hyperhive's own telemetry** — `otel.enable`
contributes the collector's port and derives the agent-facing endpoint itself.
## Built-in resource labels

8
nix/host-modules/hive-network.nix
View file

@ -93,7 +93,7 @@ in
exposeHostPorts = lib.mkOption {
type = lib.types.listOf lib.types.port;
default = [ ];
example = [ 4318 ];
example = [ 5432 ];
description = ''
TCP ports on the host that agent containers may reach at the bridge
IP (`bridgeIp`). Each listed port `P` is opened on the bridge-interface
@ -104,12 +104,6 @@ in
a database, a scratch HTTP endpoint, anything listening on
`''${bridgeIp}:P`.
Not needed for hyperhive's own telemetry: `services.hyperhive.otel.enable`
contributes its collector's port here itself and derives the
agent-facing endpoint from the bridge address. `otel.endpoint` names
where telemetry goes *after it leaves the swarm*, and is read by the
swarm's collector — it is not a bridge address.
**The host service must bind an address reachable from the bridge** —
`0.0.0.0` or the bridge IP (`bridgeIp`) — not loopback-only. The
bridge→`127.0.0.0/8` DROP rule (defence-in-depth) is unchanged: this