feat(vpn): node-level split-tunnel egress gateway Ansible role (ADR-0015)

Author the vpn_egress_gateway role + playbook that stands up the NODE-level
PIA OpenVPN tunnel on egress-gateway node(s) — the host half of ADR-0015. The
CiliumEgressGatewayPolicy steering vpn-class pods is separate GitOps against the
same contract (group vpn_egress_gateway, node label
homelab.keithjackson.dev/egress-gateway=true, host iface tun0).

Honors all four ADR-0015 invariants:
- Split-tunnel (inv 1&2): OpenVPN route-noexec + pull-filter ignore
  redirect-gateway => installs no routes; policy routing in a dedicated table
  (51820) with `ip rule from <tun0-addr>` steers ONLY Cilium-SNAT'd vpn-class
  traffic. Node default route stays on the WAN, tunnel up or down.
- Scoped nftables kill-switch (inv 3&4): own inet table, policy accept, drops
  only tunnel-sourced (@vpn_egress_gateway_src set) packets not leaving tun0 =>
  vpn-class fails closed (blackhole), node/internet-class fail open (WAN),
  never matched.

PIA creds + the proven sweden-aes-128-cbc-udp-ip .ovpn come from Ansible vault
(host-side per ADR-0015/docs-07); vault keys documented, no secret values
committed. ansible-lint (production) + yamllint clean. Not deployed: green
conformance is gated on the live tunnel (operator host creds) — see role README.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 4.8 committed 2026-08-24 01:09:19 -05:00
1 parent 38fcfadbf0
commit 2c109e2a31
14 files changed
+606

No files matched your search

@@ -0,0 +1,52 @@
# group_vars for the `vpn_egress_gateway` node(s) — ADR-0015 host tunnel secrets
The node-level VPN tunnel is **host infra**, so (per ADR-0015 / docs/07) its PIA credentials
live **host-side in Ansible vault** here — NOT in a cluster SOPS Secret. Create an encrypted
`vault.yml` in this directory (committed, encrypted; the passphrase file stays out of the repo,
see `ansible.cfg` `vault_password_file`).
## Required vault keys (operator provides the VALUES — none are committed in plaintext)
```bash
cd infra/ansible
ansible-vault create inventory/group_vars/vpn_egress_gateway/vault.yml
```
`vault.yml` must define exactly these three keys (the role maps them to its
`vpn_egress_gateway_*` vars in `roles/vpn_egress_gateway/defaults/main.yml`):
| Vault key | What it is |
|---|---|
| `vault_vpn_egress_gateway_pia_username` | PIA account username (for the `.ovpn`'s `auth-user-pass`) |
| `vault_vpn_egress_gateway_pia_password` | PIA account password |
| `vault_vpn_egress_gateway_pia_ovpn` | The **full text** of the proven PIA `.ovpn` — the same `sweden-aes-128-cbc-udp-ip.ovpn` (PIA over OpenVPN-UDP, AES-128-CBC/SHA1/RSA-2048, IP-pinned Stockholm remote `158.173.241.x:1198/udp`) currently held in the k8s `pia-custom-ovpn` Secret. Use a YAML block scalar so the inline `<ca>`/`<crl-verify>` PEM survives verbatim. |
Example skeleton (values are placeholders — DO NOT commit unencrypted):
```yaml
vault_vpn_egress_gateway_pia_username: "pXXXXXXX"
vault_vpn_egress_gateway_pia_password: "REDACTED"
vault_vpn_egress_gateway_pia_ovpn: |
client
dev tun
proto udp
remote 158.173.241.36 1198
cipher aes-128-cbc
auth sha1
auth-user-pass
...
<ca>
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
</ca>
```
> To lift the exact `.ovpn` out of the existing cluster Secret:
> `sops -d platform/vpn-egress/pia-custom-ovpn.sops.yaml` → the `sweden-aes-128-cbc-udp-ip.ovpn`
> value is the text to paste under `vault_vpn_egress_gateway_pia_ovpn`.
## Notes
- `vault.yml` is skipped by the yamllint gate (`ci/yamllint.yaml` ignores `**/vault.yml`).
- This is the Ansible-bootstrap-layer secret (host credential), distinct from the platform's
in-cluster SOPS + age secrets (ADR-0007) — different layer, different tool, by design (ADR-0015).
+7
View File
@@ -20,3 +20,10 @@ k3s_secondary
# (sudo) password comes from the vaulted group_vars/hypervisor/vault.yml.
[hypervisor]
localhost ansible_connection=local
# VPN egress-gateway node(s) — run the node-level split-tunnel OpenVPN + kill-switch
# (ADR-0015, playbooks/vpn.egress.gateway.yml). Initially just k3s-dev-3 (single gateway;
# add a second host here for Cilium Egress Gateway HA). Members are already defined above
# with their ansible_host under k3s_secondary; this group only tags the egress role target.
[vpn_egress_gateway]
k3s-dev-3