From fc3bd2a26cb86af4c798243a67270b5b69b96893 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 19 Aug 2026 00:19:13 +0200 Subject: [PATCH] docs(network): drop the otel reasoning instead of restating it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/observability.md | 26 +++++++++++--------------- nix/host-modules/hive-network.nix | 8 +------- 2 files changed, 12 insertions(+), 22 deletions(-) diff --git a/docs/observability.md b/docs/observability.md index 46f87bbd..4b23a4bb 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -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 diff --git a/nix/host-modules/hive-network.nix b/nix/host-modules/hive-network.nix index ff182902..957e5caf 100644 --- a/nix/host-modules/hive-network.nix +++ b/nix/host-modules/hive-network.nix @@ -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