Compare commits

...
Author SHA1 Message Date
atlas
fc3bd2a26c docs(network): drop the otel reasoning instead of restating it
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
2026-08-19 02:04:57 +02:00
atlas
f3625a9e60 docs(network): stop pointing exposeHostPorts at otel.endpoint
`exposeHostPorts`'s worked example told the operator to set
`services.hyperhive.otel.endpoint` to a bridge address. That was true
before the collector tiers existed. It is now actively wrong: `enable`
contributes the hive collector's port to this list itself and derives
the agent-facing endpoint, while `endpoint` names where telemetry goes
after it leaves the swarm and is read by the swarm's collector. An
operator following the old example would point the upstream link at a
bridge address.

Replace it with an example that is actually the option's job -- a
host-local service the operator runs themselves -- and say plainly that
hyperhive's own telemetry needs nothing here, which docs/observability.md
already states.
2026-08-19 02:04:57 +02:00
2 changed files with 15 additions and 19 deletions

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

View file

@ -93,16 +93,16 @@ 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
firewall, so an agent can connect to `''${bridgeIp}:P` (default
`10.42.0.1:P`).
Use this to let agents reach a host-local service e.g. an
OpenTelemetry collector for `services.hyperhive.otel.endpoint` (set
`endpoint = "http://''${bridgeIp}:P"`).
Use this to let agents reach a host-local service you run yourself
a database, a scratch HTTP endpoint, anything listening on
`''${bridgeIp}:P`.
**The host service must bind an address reachable from the bridge**
`0.0.0.0` or the bridge IP (`bridgeIp`) not loopback-only. The