ADR-0015: add non-negotiable egress invariants (default=WAN, scoped kill-switch)

Make the operator's requirement explicit: default (every pod + the nodes) egresses
the local/private WAN, never the VPN; VPN is strictly opt-in via egress-class=vpn;
the kill-switch blackholes ONLY vpn-class. The two classes fail in opposite
directions — internet fails open (WAN), vpn fails closed (blackhole). Added as ADR-0015
Invariants + a default-WAN principle in docs/03, gated by the egress-class/vpn-killswitch
conformance tests.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 4.8 committed 2026-08-24 00:52:07 -05:00
1 parent 6770087d68
commit c68349f4ab
2 files changed
+31 -1

No files matched your search

+10 -1
View File
@@ -92,7 +92,16 @@ VPN-class services: **sonarr, radarr, jackett, qbittorrent**. Per OQ-3 the desig
shared VPN connection** — not a per-service sidecar — so that **network rules are enforced outside
the service**. The steering mechanism was settled by **ADR-0015** after the original in-cluster-Gluetun
approach proved un-steerable (a Gluetun *pod*'s `tun0` is invisible to the node datapath, and
`hostNetwork` Gluetun hijacks the node's own default route). The model:
`hostNetwork` Gluetun hijacks the node's own default route).
**Default is the WAN; the VPN is strictly opt-in.** Every pod — and the nodes themselves — egress the
local/private WAN by default and **never** the VPN. Only services labeled `egress-class=vpn` are steered to
the tunnel, and the kill-switch blackholes **only** that class. The two classes fail in **opposite**
directions: `internet` fails **open** (WAN, never blackholed); `vpn` fails **closed** (blackhole, never leaks
to WAN). See the ADR-0015 invariants — implementation must not route the default through the VPN or blackhole
the wrong class.
The model:
- **Tunnel on the node, not in a pod.** One or two labeled **egress-gateway nodes** run a **host OpenVPN
systemd service** — **PIA over OpenVPN-UDP** (provider/protocol per ADR-0013; "non-TCP or better"),