From 9b24978342cdd50d29295c65c821338ced20468e Mon Sep 17 00:00:00 2001 From: gilgamezh Date: Sun, 31 May 2026 10:20:16 +0200 Subject: [PATCH] docs: add CLAUDE.md (GitOps flow + AirVPN/gluetun DNS gotcha) Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..15a3c7c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,39 @@ +# turingpi + +Home k3s cluster on a Turing Pi (arm64 nodes), GitOps-managed by ArgoCD. + +## Deploying changes + +- Apps are ArgoCD `Application`s in `applications/*.yaml`, pointing at an **internal Gitea** + repo (`gitea-http.gitea.svc.cluster.local`), `targetRevision: HEAD`. +- The git remote is `gitea` (`git@192.168.222.26:admin/turingpi.git`); working branch is **`master`**. +- To deploy: **commit and push to `gitea/master`**. Apps have `syncPolicy.automated` with + `selfHeal: true`, so direct `kubectl patch`/`edit` is reverted — changes must go through git. +- Argo polls Gitea every ~3 min. Force a sync with: + `kubectl -n argocd annotate application argocd.argoproj.io/refresh=hard --overwrite` +- Helm values: `helm-values/_values.yaml`. Custom charts: `custom_helm_charts//`. + +## Gotchas + +### qbittorrent + gluetun (AirVPN) — DNS / restart loop + +AirVPN blocks outbound **DNS-over-TLS (tcp/853)** to force its own resolver. Gluetun's default +`DOT=on` resolver (127.0.0.1) therefore never gets answers, **all DNS fails**, and the VPN +startup healthcheck (`lookup cloudflare.com`) times out — gluetun restarts the VPN every ~6s in a +permanent loop. The pod still shows `2/2 Running` with 0 restarts, so it looks healthy while +having no usable network. + +The gluetun sidecar in `helm-values/qbittorrent_values.yaml` **must** keep: + +```yaml +- name: DOT + value: "off" +- name: DNS_ADDRESS + value: "10.128.0.1" # AirVPN's pushed resolver, reached over the tunnel — no DNS leak +``` + +Diagnose: gluetun logs repeat `restarting VPN ... lookup ... i/o timeout`. Confirm with +`ping 8.8.8.8` (works) and `nslookup x 10.128.0.1` (works) but `curl 1.1.1.1:853` (times out). + +Note: the `7e0a38d` "pin gluetun to v3.41.1" commit message falsely claimed v3.41.1 fixed this +DNS timeout. It did not — don't trust that claim.