From d97659c06afa980fa8dd5d2d1091084e4aad445c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?m=C3=BCde?= Date: Mon, 13 Jul 2026 23:58:54 +0200 Subject: [PATCH] docs: add the network topology map to network.md --- docs/network.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/docs/network.md b/docs/network.md index b3c2a7ad..4fbc8dc9 100644 --- a/docs/network.md +++ b/docs/network.md @@ -10,6 +10,69 @@ whenever hyperhive is enabled. Configured via > `services.hyperhive.network.upstreamDns` options were removed; a > config that still sets one fails eval with a removal message. +## Network map + +One picture of the whole hive. There are two planes: **infra +containers share the host netns** and bind host ports directly; +**compute containers (agents + CI) each get a private netns** behind +the bridge. The unix-socket control plane rides the VFS and is +untouched by any of it. + +``` + internet + │ uplink NIC — NAT MASQUERADE for the + │ bridge subnet (10.42.0.0/24 default) +┌──────────────────────────┴─────────────────────────────────────────┐ +│ host netns — the host itself plus gateway / forge / matrix │ +│ │ +│ nginx :80/:443 [hive-gateway] │ +│ dnsmasq 10.42.0.1:53 (DNS) + :67 (DHCP) [hive-gateway] │ +│ forgejo :3000 http, :2222 git-ssh [hive-forge] │ +│ tuwunel :8008 client API [hive-matrix] │ +│ hive-c0re dashboard 127.0.0.1:7000 (host service) │ +│ wg-hive :51820/udp — swarm mesh, when enabled (host iface) │ +│ │ +│ hive-br0 10.42.0.1/24 │ +│ ┌──────────┼──────────────┐ │ +└──────────────┼──────────┼──────────────┼───────────────────────────┘ + vb-h- vb-h- vb-hive-ci veth pairs + │ │ │ + ┌────┴────┐ ┌───┴─────┐ ┌──────┴──┐ one private netns + │ agent a │ │ agent b │ │ hive-ci │ each; eth0 leases + │ eth0 │ │ eth0 │ │ eth0 │ from the DHCP pool + └─────────┘ └─────────┘ └─────────┘ +``` + +| container | netns | IPv4 | listens / reached via | +| -------------- | ----------------------- | -------------------- | -------------------------------------------------------------------------------------------- | +| `hive-gateway` | host (shared) | host addresses | nginx `:80`/`:443` (every vhost); dnsmasq `bridgeIp:53` + DHCP `:67` on the bridge | +| `hive-forge` | host (shared) | host addresses | forgejo `:3000` http, `:2222` git-ssh; fronted by the `forge.` vhost | +| `hive-matrix` | host (shared) | host addresses | tuwunel `:8008` (+ optional federation port); fronted by the matrix vhost | +| `hive-ci` | private, veth on bridge | DHCP pool | outbound only (runner → forge); no inbound surface | +| `h-` | private, veth on bridge | DHCP pool | web UI via UDS `/run/hive-agent/` → nginx sub-path; in-container UI port hashed 8100–8999 | + +The flows, end to end: + +- **DHCP** — agent `dhcpcd` broadcasts on `eth0` → veth → bridge → + host firewall (udp 67 hole) → dnsmasq pool → lease + router option. +- **DNS** — agents query `bridgeIp:53`; hive zones are answered + authoritatively with the bridge IP, everything else forwards to the + host's resolvers (see *Resolver behaviour* below). +- **HTTP** — `forge.` / matrix / dashboard names all resolve + to the bridge IP, land on nginx `:80`/`:443`, and proxy to forgejo + `:3000`, tuwunel `:8008`, hive-c0re `127.0.0.1:7000`, or a per-agent + UI unix socket. +- **Internet egress** — agent default route points at the bridge IP; + the host forwards + masquerades out its uplink. +- **Swarm** — peer hives connect over the `wg-hive` WireGuard mesh + and reach each other's gateway/forge across it + ([`docs/swarm.md`](swarm.md)). +- **Control plane (no network)** — per-agent broker socket + `/run/hive/mcp.sock`, privileged helper `/run/hive/priv.sock`, + operator admin `/run/hyperhive/host.sock`, and the per-agent UI + sockets under `/run/hive-agent/` are unix domain sockets + bind-mounted through the VFS; private netns does not affect them. + ## Container shape (where dnsmasq lives) Co-located in the existing `hive-gateway` container — single