From 94dd6da14c03c0467424f35dc9b9b10dc780a4c2 Mon Sep 17 00:00:00 2001 From: sjat Date: Tue, 16 Jun 2026 07:54:09 +0200 Subject: [PATCH] docs(netbird): describe gRPC routing as the deployed Content-Type matcher README/SECURITY said gRPC was path-matched (/management.ManagementService/* etc.); the deployed Caddy route selects gRPC by Content-Type: application/grpc* (NetBird's own external-proxy example). Reconciled the prose to what actually runs. Co-Authored-By: Claude Opus 4.8 (1M context) --- roles/netbird_coordinator/README.md | 13 ++++++++----- roles/netbird_coordinator/SECURITY.md | 6 +++--- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/roles/netbird_coordinator/README.md b/roles/netbird_coordinator/README.md index b2e915d..4145535 100644 --- a/roles/netbird_coordinator/README.md +++ b/roles/netbird_coordinator/README.md @@ -26,12 +26,15 @@ This role does **not** add the Caddy route. The route is a separate task and mus front several upstreams on `netbird-server` over the boma network, all to the same backend: -- HTTP — `/api/*`, `/oauth2/*` -- Native gRPC (h2c) — `/signalexchange.SignalExchange/*`, `/management.ManagementService/*` -- WebSocket — `/relay*`, `/ws-proxy/*` (upgrade + long timeouts) -- Dashboard catch-all — `/*` → `netbird-dashboard` +- Native gRPC (signal + management) — matched by **`Content-Type: application/grpc*`** + (not by path) → `h2c://netbird-server:80` +- HTTP + WebSocket — paths `/relay*`, `/ws-proxy/*`, `/api/*`, `/oauth2/*` → `netbird-server:80` +- Dashboard catch-all — `/*` → `netbird-dashboard:80` -gRPC needs HTTP/2 (h2c) upstream support; WS/gRPC need extended timeouts. +This matches NetBird's own external-proxy Caddy example: gRPC (the +`/management.ManagementService/*` + `/signalexchange.SignalExchange/*` services) is +selected by content-type rather than enumerated by path. gRPC needs HTTP/2 (h2c) +upstream support; WS/gRPC need long timeouts (Caddy sets none by default). ## Variables — `netbird_coordinator__*` diff --git a/roles/netbird_coordinator/SECURITY.md b/roles/netbird_coordinator/SECURITY.md index 4078891..9f94971 100644 --- a/roles/netbird_coordinator/SECURITY.md +++ b/roles/netbird_coordinator/SECURITY.md @@ -5,9 +5,9 @@ - **Published ports:** - `443/tcp` — **not host-published**; reached via the M4a Caddy reverse proxy on the `boma` Docker network. Caddy fronts the dashboard SPA, the management REST API - (`/api`), the embedded Dex IdP (`/oauth2`), native gRPC over h2c - (`/management.ManagementService/*`, `/signalexchange.SignalExchange/*`), and the - relay WebSocket (`/relay*`, `/ws-proxy/*`). TLS terminates at Caddy (Let's Encrypt + (`/api`), the embedded Dex IdP (`/oauth2`), native gRPC over h2c (the management + + signal services, matched by `Content-Type: application/grpc*`), and the relay + WebSocket (`/relay*`, `/ws-proxy/*`). TLS terminates at Caddy (Let's Encrypt HTTP-01); upstreams listen plain `:80` on the internal network only. - `3478/udp` — **STUN, host-published directly** (`netbird-server`'s only host port), bypassing Caddy because STUN is UDP and not HTTP.