Files
home-network-k3s/decisions/adr-0008-vpn-egress-model.md
T
jakman85andClaude Opus 4.8 e8c555cfeb Initial baseline: home platform (k3s + Longhorn) specification repository
Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision &
requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap
(phases + workstreams), and AI-agent coordination (roles, protocol,
definition-of-done, task board).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-15 22:37:56 -05:00

43 lines
2.5 KiB
Markdown

# ADR-0008 — VPN egress model: Gluetun sidecar (default) + Cilium Egress Gateway
- Status: Accepted
- Date: 2026-08-15
- Serves: R-NET-05, R-NET-06, R-NET-07
- Supersedes: —
## Context
A subset of services (sonarr, radarr, jackett, qbittorrent) must egress **only** through a commercial
VPN, with a **kill-switch** guaranteeing no leak to the plain internet if the tunnel drops. Egress
class must be a declarative service property (`egress: vpn`) that doesn't force a workload rewrite.
## Decision
Adopt a **two-pattern** model behind the single `egress: vpn` contract, with **Gluetun sidecar as the
default** for the initial catalog:
- **Default — Pattern A: Gluetun sidecar per pod.** A Gluetun container holds the WireGuard/OpenVPN
tunnel; the app shares its network namespace. Gluetun's built-in **firewall kill-switch** blocks
all non-tunnel egress by default — satisfying R-NET-06 intrinsically and per-service.
- **Available — Pattern B: central VPN egress gateway + Cilium Egress Gateway.** One (HA) gateway
holds the tunnel; Cilium Egress Gateway steers `vpn`-labeled pods through it, with policy denying
any fallback to the internet path. Use when tunnel count must be minimized.
The service-facing contract is identical for both: declare `egress: vpn`; the platform wires the
chosen pattern. Kill-switch behavior is a hard acceptance gate for both.
## Alternatives considered
- **Central gateway only** — fewer tunnels but a shared failure domain and more complex kill-switch
guarantees across the fabric; kept as Pattern B, not the default.
- **Node-level policy routing / per-node VPN** — couples egress to node identity, harder to reason
about per-service; rejected as the primary model.
- **App-native VPN config** — rejected: not declarative, not uniform, easy to misconfigure and leak.
## Consequences
- Per-service isolation and an intrinsic kill-switch out of the box (Pattern A).
- More sidecars/tunnels at scale (Pattern A) — Pattern B is the escape hatch if the VPN provider
limits concurrent tunnels/egress IPs (OQ-3).
- Kill-switch must be **fault-tested** (tunnel forced down ⇒ zero internet egress) as a standing
acceptance gate, not a one-time check ([03](../docs/03-networking-isolation-and-egress.md), R-NET-06).
- VPN credentials are SOPS-encrypted (ADR-0007). WireGuard preferred over OpenVPN where supported.
## Open questions
- **OQ-3** — VPN provider/protocol and concurrent-tunnel/egress-IP limits (drives Pattern A vs B and
gateway HA).