jakman85andClaude Opus 4.8
95b4b6af21
Gluetun does not support Private Internet Access over WireGuard (upstream: native support "cannot be added... slow work in progress"; confirmed live rejecting the provider on v3.40/v3.41/latest). PIA in Gluetun is OpenVPN-only. Amend ADR-0013 to PIA over OpenVPN-UDP. The egress ARCHITECTURE is unchanged (single shared gateway, central kill-switch/fail-closed, native PF, Cilium egress steering, active/standby) and R-NET-05/06/07 remain met; only the tunnel protocol changes. OpenVPN-UDP satisfies "non-TCP", and Gluetun's HTTP control API (health + forwarded-port lookup) is what the shared-gateway topology needs. thrnz/docker-wireguard-pia retained as a documented WireGuard fallback. Propagated the protocol correction to all active specs: ADR-0013 (+amendment note), decisions/README, docs/00, docs/01, docs/03, docs/07, agents/task-board. Superseded ADR-0008/0012 left immutable as historical record. Co-Authored-By: Claude Opus 4.8 <[email protected]>
3.2 KiB
3.2 KiB
Architecture Decision Records (ADRs)
ADRs are an append-only ledger of the significant technology and pattern choices for this platform. Each records the context, the decision, the rejected alternatives, and the requirements it serves. Do not edit an accepted decision in place — supersede it with a new ADR.
ADRs are specifications and are immutable to AI agents (R-TEST-06). Agents may draft a proposed ADR and escalate it, but only the human operator/architect approves/accepts or edits ADRs. See
../AGENTS.md§3 and §11.
Process (read before proposing a change)
- To change a decision, create a new ADR with the next number and set
Status: Proposed,Supersedes: ADR-XXXX. (Agents draft + escalate; the human approves.) - State what new information invalidates the old decision.
- On approval, set the new ADR
Acceptedand the old oneSuperseded by: ADR-YYYY. - Never silently re-interpret an accepted ADR (see
../AGENTS.md§3).
Template
# ADR-XXXX — <title>
- Status: Proposed | Accepted | Superseded by ADR-YYYY
- Date: <YYYY-MM-DD>
- Serves: <requirement IDs, e.g. R-NET-01, R-NET-06>
- Supersedes: <ADR-ZZZZ or —>
## Context
<forces, constraints, why a decision is needed>
## Decision
<what we chose, stated decisively>
## Alternatives considered
<options and why rejected>
## Consequences
<positive, negative, follow-ups, risks>
Index
| ADR | Title | Status | Serves |
|---|---|---|---|
| 0001 | Kubernetes distribution: k3s | Accepted | R-PLAT-01 |
| 0002 | CNI & network policy & ingress: Cilium + Gateway API | Accepted | R-NET-01..07, R-DNS-01 |
| 0003 | Distributed storage: Longhorn (+ bulk tier, Velero) | Accepted | R-STATE-01..04 |
| 0004 | GitOps engine: Flux CD | Accepted | R-GITOPS-01..03 |
| 0005 | VM workloads: KubeVirt + CDI | Accepted | R-PLAT-03 |
| 0006 | TLS: cert-manager + Let's Encrypt (DNS-01) | Accepted | R-TLS-01..03 |
| 0007 | Secrets: SOPS + age | Accepted | R-SEC-01 |
| 0008 | VPN egress model: Gluetun sidecar + Cilium Egress Gateway | R-NET-05/06 | |
| 0009 | Automated updates: Flux image automation + Renovate | Accepted | R-UPD-01..03 |
| 0010 | Conformance testing: automated, reproducible, behavior-based | Accepted | R-TEST-01..06 |
| 0011 | Conformance test tooling: Kyverno + Chainsaw | Accepted | R-TEST-01..05 |
| 0012 | VPN egress: single shared in-cluster ExpressVPN gateway | R-NET-05/06/07 | |
| 0013 | VPN provider: PIA via Gluetun (OpenVPN-UDP + port forwarding) | Accepted (amended 2026-08-22) | R-NET-05/06/07 |
| 0014 | Identity Provider: Keycloak (SSO via OIDC + forward-auth) | Accepted | R-IDP-01..06 |