Operator turned off ExpressVPN auto-renew and purchased PIA. The single-shared- gateway model is retained; provider/client/protocol change to PIA via Gluetun over WireGuard with native port forwarding (qbittorrent-natmap port-sync). Simpler than ExpressVPN: no custom OpenVPN config, just PIA user/pass SOPS-encrypted; Gluetun provides the built-in kill-switch. Updated: ADR-0013 (new) + ADR-0012 superseded + index; docs 00,01,03,07; task board (T-3.2p/T-3.2, OQ-3). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
54 lines
3.4 KiB
Markdown
54 lines
3.4 KiB
Markdown
# ADR-0013 — VPN provider: PIA via Gluetun (WireGuard + native port forwarding)
|
|
- Status: Accepted
|
|
- Date: 2026-08-15
|
|
- Serves: R-NET-05, R-NET-06, R-NET-07
|
|
- Supersedes: [ADR-0012](adr-0012-vpn-egress-single-expressvpn-gateway.md)
|
|
|
|
## Context
|
|
ADR-0012 kept the operator's required model — a single shared in-cluster VPN gateway with rules
|
|
enforced outside the service — but named **ExpressVPN** as the provider, which forced a custom
|
|
OpenVPN-UDP setup because ExpressVPN is **not a first-class containerized (Gluetun) provider**. The
|
|
operator has since **turned off ExpressVPN auto-renew and purchased Private Internet Access (PIA)**,
|
|
which *is* first-class in Gluetun. The egress **model is unchanged**; only the provider, client, and
|
|
protocol change — so ADR-0012 is superseded.
|
|
|
|
## Decision
|
|
The single shared in-cluster VPN gateway runs **Gluetun** configured for **PIA** over **WireGuard**,
|
|
with Gluetun's **native automated port forwarding** for qBittorrent:
|
|
|
|
- **Provider/client:** PIA via the **Gluetun** container as the gateway VPN client (Gluetun provides
|
|
the built-in **kill-switch/firewall**, health checks, and auto-reconnect).
|
|
- **Protocol:** **WireGuard** (UDP) — satisfies "non-TCP, UDP or better" and is a strict upgrade over
|
|
ExpressVPN's OpenVPN-UDP.
|
|
- **Credentials:** just the **PIA username/password**, stored **SOPS-encrypted** ([ADR-0007](adr-0007-secrets-sops-age.md)).
|
|
No manual `.ovpn` extraction (the ExpressVPN prerequisite is gone).
|
|
- **Port forwarding:** Gluetun native (`VPN_PORT_FORWARDING=on`, provider `private internet
|
|
access`) on a **PF-enabled PIA region**; a small **port-sync helper** (e.g. `qbittorrent-natmap`)
|
|
writes the assigned port into qBittorrent so it tracks reconnects — keeping it hands-off (R-UPD).
|
|
- **Model retained from ADR-0012:** one shared tunnel; `vpn`-class pods steered through the gateway
|
|
with **no independent egress path**; **central kill-switch (fail-closed)**; rules enforced outside
|
|
the service; gateway run **active/standby**; alert on tunnel state.
|
|
|
|
## Alternatives considered
|
|
- **ExpressVPN (ADR-0012)** — dropped: not Gluetun-native, needed a custom OpenVPN workaround; and the
|
|
operator's subscription is lapsing.
|
|
- **ProtonVPN** — equally good fit (Gluetun-native NAT-PMP PF, WireGuard); viable if PIA
|
|
disappoints, but the operator has purchased PIA.
|
|
- **AirVPN** — WireGuard works in Gluetun but automated PF is not integrated (static port only);
|
|
less hands-off.
|
|
- **Mullvad** — no port forwarding since 2023 → degraded qBittorrent seeding; rejected for this
|
|
torrent-adjacent stack.
|
|
|
|
## Consequences
|
|
- **Simpler and cleaner than ADR-0012:** the gateway is a stock Gluetun container (env-var config),
|
|
not a bespoke OpenVPN build; kill-switch and port forwarding are built in.
|
|
- **PF caveat:** PIA port forwarding is available only on **specific PF-enabled server regions** and
|
|
the assigned port can change on reconnect → the **port-sync helper** and a PF-capable region are
|
|
required; alert if PF acquisition fails.
|
|
- Single shared egress IP + single failure domain remain (mitigated by active/standby + alerting).
|
|
- Credentials are a single SOPS-encrypted PIA username/password; rotation = re-encrypt + commit.
|
|
- Kill-switch + correct-egress-IP + PF remain **fault-injection acceptance tests** in dev/test
|
|
(R-TEST-05, [14](../docs/14-testing-and-conformance.md)).
|
|
- If PIA proves unsatisfactory, **ProtonVPN** is the pre-vetted fallback (superseding ADR, operator
|
|
decision).
|