Skip to content

0037. Dedicated private API Gateways

  • Status: accepted
  • Date: 2026-07-17
  • Deciders: lusoris
  • Related: BUG-43, BUG-44

Context

SABnzbd browser integrations cannot complete an Authentik browser flow and therefore use the SABnzbd API key on a distinct hostname. The first design attached that hostname to main-home and main-office and relied on exact RFC1918 split DNS. Cloudflare's remotely managed wildcard tunnels also use those Gateways as catch-all origins. Once public wildcard DNS resolved the hostname, requests reached SABnzbd despite the private DNS intent.

Decision

Create one reusable LAN-only Gateway per site: private-home at 10.1.30.13 and private-office at 10.2.30.12. Private API routes may attach only to Gateways marked security.cauda.dev/exposure=private-lan-only. Each listener and route uses the exact hostname, and LAN DNS maps it directly to the local private VIP.

Every declarative cloudflared configuration must deny the exact private hostname before its catch-all and must never use a private Gateway as an origin. Public DNS non-resolution is defense in depth, not the security boundary. The coherency checker enforces these contracts.

Consequences

  • A Cloudflare wildcard or catch-all aimed at a general Gateway cannot reach a private API route.
  • The private pair is shared by reviewed LAN-only APIs; no per-application Gateway is created.
  • Cilium's current shared cilium-envoy DaemonSet serves the new Gateways, so the pair adds Services, VIPs and listener configuration but no resident proxy pods.
  • Cloudflare remote-state repair remains necessary under BUG-43, but it is no longer the only barrier protecting this API.

Rejected alternatives

  • Split DNS alone: public wildcard resolution bypassed the assumption.
  • Path guards only in mounted cloudflared ConfigMaps: remote tunnel configuration currently overrides those files.
  • One Gateway per application: unnecessary control-plane and address sprawl.