0 Fork 0

Files

T

jakman85andClaude Opus 4.8 015b423353 feat(vpn): enable vpn-egress on OpenVPN-UDP; align docs to ADR-0013 amendment

Gluetun cannot do PIA over WireGuard (upstream unsupported; live "provider name
is not valid for Wireguard"). Operator approved OpenVPN-UDP and ADR-0013 was
amended in the spec. This aligns the impl:

- platform/kustomization.yaml: re-enable `- vpn-egress` (Phase 3, OpenVPN-UDP)
- gluetun-gateway.yaml: clean stale WireGuard comments (header, image note,
  VPN_TYPE/creds comments); config already VPN_TYPE=openvpn
- README.md: PIA-over-OpenVPN, status=enabled, steering iface wg0 -> tun0
- DECISIONS-LOG.md: disk/drive incident (k3s -> NVMe; failing Seagate) + Phase-3
  OpenVPN resolution

Stale WireGuard comments inside the operator's encrypted pia-credentials.sops.yaml
header left untouched (editing breaks the SOPS MAC; cosmetic).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

2026-08-22 14:49:16 -05:00

4.2 KiB

Raw Blame History

platform/vpn-egress — shared VPN egress gateway (Phase 3, ADR-0013)

Single shared Gluetun gateway: PIA over OpenVPN-UDP (ADR-0013 amendment — Gluetun does not support PIA over WireGuard), built-in kill-switch, native port forwarding. vpn-class services (sonarr, radarr, jackett, qbittorrent) egress only through this tunnel; internet-class services go out the normal WAN. Serves R-NET-05/06/07.

STATUS: enabled in platform/kustomization.yaml (Phase 3). pia-credentials SOPS secret is provisioned. Remaining work: validate the tunnel comes up + correct egress IP, then the egress-steering mechanism below (the hard part) and the kill-switch conformance test.

Pieces

gluetun-gateway.yaml — the Gluetun Deployment (replicas: 1, Recreate) + the gluetun-control Service (control API :8000 for forwarded-port lookup + tunnel-state health). Kill-switch = FIREWALL=on.
pia-credentials (SOPS) — PIA username/password only; Gluetun ships PIA's OpenVPN configs.

Operator hand-off (when deploying Phase 3)

Provision pia-credentials (see bootstrap/sops/secret-templates/pia-credentials.yaml.example, namespace vpn-egress, keys username/password) → sops -e -i → uncomment it in kustomization.yaml.
cluster-vars (already defined in clusters/base/cluster-vars.yaml; a ConfigMap — values are plain strings under data:, injected into the ${...} tokens by Flux postBuild.substituteFrom). Confirm or override:
- PIA_REGION — a port-forwarding-capable PIA region (default Sweden; e.g. Netherlands, CA Toronto, Switzerland; NOT a US region — those lack PF). Gluetun SERVER_REGIONS.
- CLUSTER_POD_CIDR — the Cilium cluster-pool pod CIDR (default 10.0.0.0/8; pods get 10.x, confirmed live — NOT the k3s 10.42.0.0/16). Gluetun FIREWALL_OUTBOUND_SUBNETS. Per-env overrides go in clusters/<env>/kustomization.yaml as a cluster-vars JSON patch (- op: replace, path: /data/PIA_REGION, value: "…"). With the self-managing root, a git push auto-applies (no manual kubectl apply -k).
Enable - vpn-egress in platform/kustomization.yaml (Phase 3).

Egress steering — the DESIGN DECISION (needs live validation)

The hard part: routing vpn-class pods through this ONE shared tunnel. Cilium Egress Gateway (CiliumEgressGatewayPolicy) SNATs matched pods out of a gateway node's interface — it does not natively route through a pod's tunnel. Options considered:

Cilium Egress Gateway → the Gluetun node's tunnel interface (recommended). Pin Gluetun to a node; a CiliumEgressGatewayPolicy selects pods labeled homelab.keithjackson.dev/egress-class=vpn and egresses them via that node's tunnel interface (tun0, OpenVPN). If the tunnel drops, tun0 is gone → traffic has no egress path → fail-closed (the kill-switch behavior R-NET-06 needs). This is the most Cilium-native fit but requires Gluetun's tunnel interface to be visible to the node datapath (hostNetwork Gluetun, or a shared netns) — the detail to VALIDATE.
Gateway-pod routing: client pods default-route to the Gluetun pod IP (init-container + NET_ADMIN, or a Multus secondary interface); Gluetun forwards+NATs via the tunnel. Works without Cilium egress gateway but is more moving parts and pod-IP-fragile.
Per-pod Gluetun sidecar — explicitly REJECTED by ADR-0013 (single shared gateway preferred).

Plan: validate option 1 against a live PIA tunnel (confirm tun0 on the Gluetun node + a CiliumEgressGatewayPolicy steering egress-class=vpn pods, then run the egress-class (R-NET-05/07) and vpn-killswitch (R-NET-06) conformance tests). Fall back to option 2 if the interface isn't addressable. The CiliumEgressGatewayPolicy is intentionally NOT committed until validated, to avoid shipping an untested datapath policy.

Port forwarding (qBittorrent) — follow-up

PIA assigns a forwarded port that can change on reconnect. A small port-sync helper (qbittorrent-natmap) reads the current port from the gluetun-control API (:8000 /v1/openvpn/portforwarded) and writes it into qBittorrent, keeping it hands-off (R-UPD). Authored alongside the qBittorrent app (Phase 6 apps / or here when qBittorrent lands).

4.2 KiB Raw Blame History