e0010 - Cloudflare Tunnel — Deploy-Anleitung
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/e-externe-erreichbarkeit/e0010-cloudflare-deploy.md
Cloudflare Tunnel — Deploy-Anleitung
Diese Anleitung deckt den Rollout- und Day-2-Betrieb des
cloudflared-ArgoCD-Apps ab: Erstdeployment, Verifikation, neuen Dienst
freigeben, Secrets rotieren, Troubleshooting.
Konzept, Architektur und Erstinstallation (Tunnel anlegen, Domain zu
Cloudflare hinzufügen, Credentials versiegeln) stehen in
capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md. Diese Anleitung
setzt voraus, dass du dort bis einschließlich Schritt 5
(values.yamlbefüllt) durch bist.
Inhaltsverzeichnis
- Voraussetzungen
- Erstdeployment
- Rollout verifizieren
- Neuen Dienst freigeben
- Dienst wieder entfernen
- Credentials rotieren
- Skalierung & Ausfallsicherheit
- Troubleshooting
- Rollback
Voraussetzungen
- Tunnel via
cloudflared tunnel createangelegt (capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md, Schritt 2). tunnel.idundtunnel.encryptedCredentialsJsonin
argocd/apps/tech/cloudflared/values.yamleingetragen.- Mindestens ein DNS-Route-Eintrag via
cloudflared tunnel route dns
angelegt (capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md, Schritt 4). - ArgoCD läuft und das Root-ApplicationSet ist aktiv
(argocd/bootstrap/root-applicationset.yaml). - Sealed-Secrets-Controller ist deployt (
argocd/apps/tech/sealed-secrets/).
Erstdeployment
Wie jede andere App in diesem Repo läuft das Deployment rein über Git —
kein zusätzlicher Ansible- oder Helm-Befehl nötig:
git add argocd/apps/tech/cloudflared
git commit -m "feat(cloudflared): add Cloudflare Tunnel for external access"
git push
ArgoCD erkennt das neue Verzeichnis argocd/apps/tech/cloudflared/ innerhalb
von ca. 3 Minuten, legt die Application cloudflared im gleichnamigen
Namespace an und synct sie automatisch (syncPolicy.automated im
Root-ApplicationSet).
Sync-Status prüfen:
ssh [email protected] \
'sudo kubectl -n argocd get application cloudflared'
# Details/Fehler
ssh [email protected] \
'sudo kubectl -n argocd describe application cloudflared'
Manuellen Sync erzwingen (falls ArgoCD wartet):
ssh [email protected] \
'sudo kubectl -n argocd patch application cloudflared \
-p "{\"operation\":{\"sync\":{}}}" --type merge'
Rollout verifizieren
Pods laufen (2 Replicas, siehe values.yaml → replicaCount):
ssh [email protected] 'sudo kubectl -n cloudflared get pods'
Logs — Tunnel sollte "Registered tunnel connection" melden:
ssh [email protected] \
'sudo kubectl -n cloudflared logs deploy/cloudflared --tail=50'
Tunnel-Health im Cloudflare-Dashboard:
Zero Trust Dashboard → Networks →
Tunnels → homeserver sollte Healthy mit mehreren aktiven
Connections (eine pro Replica × i. d. R. 4 Edge-Verbindungen) anzeigen.
Externer Zugriffstest — wichtig: über Mobilfunknetz oder fremdes WLAN,
NICHT über das Heimnetz/Tailscale testen, sonst prüfst du versehentlich
nur den internen Traefik-Pfad:
curl -I https://wiki.deine-domain.de
Erwartet: HTTP/2 200 (oder ggf. eine Cloudflare-Access-Login-Seite,
falls Option B aus capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md aktiv ist).
Neuen Dienst freigeben
argocd/apps/tech/cloudflared/values.yaml bleibt für Apps im TECH-Cluster unangetastet — sie enthält
dafür eine einzige Wildcard-Regel (*.deine-domain.de), die pauschal an Traefik des TECH-Clusters
weiterreicht. Nur Apps im PROD-Cluster brauchen eine eigene Regel, siehe den Hinweis weiter unten. Die Wildcard-Regel
gilt unabhängig vom Tier (siehe capulus-core/c-netzwerk-dns/c0040-domain-tiers.md, warum eine
Regel pro Tier bei cloudflared technisch nicht funktioniert). Freigeben
passiert stattdessen direkt in der values.yaml des jeweiligen Dienstes,
analog zum internen *.homeserver-Host — mit Bindestrich statt Punkt
vor dem Tier. Kompletter Ablauf am Beispiel Grafana:
Mit der empfohlenen Wildcard-DNS-Route aus
capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md, Schritt 4
ist dafür kein DNS-Schritt mehr nötig — grafana-tech.deine-domain.de
löst durch den bestehenden *-Record bereits zum Tunnel auf.
# argocd/apps/tech/monitoring/values.yaml (Beispiel Grafana, Tier "tech")
grafana:
ingress:
hosts:
- grafana.tech.homeserver
- grafana-tech.deine-domain.de # neu — macht Grafana extern erreichbar
Nur falls du dich in capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md für die Alternative mit expliziten
Einzel-Records entschieden hast: zusätzlich
cloudflared tunnel route dns homeserver grafana-tech.deine-domain.de
ausführen.
Läuft die App im PROD-Cluster (z. B. Nextcloud, Immich, Wiki.js, Xibo), reicht der
Wildcard-Record nicht: er zeigt auf den TECH-Tunnel, dessen Traefik die PROD-App nicht kennt
(404). Der DNS-Eintrag bleibt trotzdem derselbe, die Weiterleitung steht in
argocd/apps/tech/cloudflared/values.yaml: eine eigene Regel je Host, vor dem Wildcard, die an den
Traefik des PROD-Clusters weiterreicht:- hostname: "nextcloud-prod.deine-domain.de" service: https://192.168.178.99:443 originRequest: caPool: /etc/cloudflared/origin-ca.pem originServerName: nextcloud.prod.homeserverEin
cloudflared tunnel route dns-Aufruf und ein Eintrag im PROD-Tunnel sind dafür nicht nötig. Zieht eine App von
TECH nach PROD um, kommt die Regel dazu, zieht sie zurück, entfällt sie, siehe
c0040.
git add argocd/apps/tech/monitoring/values.yaml
git commit -m "feat(monitoring): expose grafana externally"
git push
ArgoCD synct die App, Traefik übernimmt die neue Ingress-Regel automatisch
(kein Neustart von cloudflared nötig — der bekommt von alldem gar nichts
mit, seine Wildcard-Regel matchte den Hostnamen ja schon vorher, nur ohne
dass Traefik dahinter eine passende Route hatte). Testen:
curl -I https://grafana-tech.deine-domain.de
Denk an Cloudflare Access,
falls der neue Dienst nicht komplett offen im Internet stehen soll.
Dienst wieder entfernen
Einfach den externen Host wieder aus ingress.hosts der App entfernen —
Traefik findet danach keine passende Route mehr, cloudflareds
Wildcard-Regel matcht zwar weiterhin, liefert aber (über Traefiks eigenen
404) denselben Effekt wie vorher defaultService: http_status:404:
# grafana-tech.deine-domain.de aus ingress.hosts in monitoring/values.yaml löschen, dann
git add argocd/apps/tech/monitoring/values.yaml
git commit -m "feat(monitoring): remove grafana from external access"
git push
Nur bei expliziten Einzel-Records (Alternative aus capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md):
zusätzlich denCNAMEim Cloudflare-Dashboard unter DNS → Records
löschen, sonst bleibt der verwaiste Record stehen (harmlos, aber
unübersichtlich).
Credentials rotieren
Falls die credentials.json kompromittiert sein könnte (z. B. versehentlich
unverschlüsselt geteilt):
# 1. Alten Tunnel löschen (invalidiert die alte credentials.json sofort)
cloudflared tunnel delete homeserver
# 2. Neuen Tunnel anlegen
cloudflared tunnel create homeserver
# 3. Neue Tunnel-ID + neu versiegelte Credentials in values.yaml eintragen
# (siehe capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md, Schritt 2 + 3)
# 4. DNS-Route(n) neu anlegen (zeigen sonst noch auf die alte Tunnel-ID)
# Mit Wildcard-Setup reicht ein einziger Befehl für alle Hostnamen:
cloudflared tunnel route dns homeserver "*.deine-domain.de"
# Bei expliziten Einzel-Records (Alternative) stattdessen pro
# aktivem Hostnamen wiederholen:
# cloudflared tunnel route dns homeserver wiki.deine-domain.de
# cloudflared tunnel route dns homeserver ntfy.deine-domain.de
git add argocd/apps/tech/cloudflared/values.yaml
git commit -m "fix(cloudflared): rotate tunnel credentials"
git push
Skalierung & Ausfallsicherheit
cloudflared unterstützt mehrere gleichzeitige Replicas für denselben
Tunnel nativ (kein Leader-Election-Mechanismus nötig — jede Replica hält
eigene Edge-Connections). Die Replica-Zahl wird nicht mehr manuell über
replicaCount gepflegt, sondern per HPA automatisch zwischen 2 (Minimum,
für die zwei unabhängigen Edge-Verbindungen) und 4 geregelt, ausgelöst ab
CPU 70% (autoscaling in values.yaml; Details für alle Apps:
../b-kubernetes-gitops/b0040-hpa-autoscaling.md). replicaCount: 2 bleibt
als Fallback-Wert stehen, greift aber nur, falls autoscaling.enabled
auf false gesetzt wird.
Da der Homeserver der einzige Dauerläufer ist (TECH läuft direkt darauf, die
PROD-VM ebenfalls, siehe a0010),
schützt eine höhere Replica-Zahl primär vor Pod-Neustarts/Rolling-Updates, nicht
vor einem Host-Ausfall — die grundsätzliche Verfügbarkeit hängt weiterhin am
Homeserver selbst.
Troubleshooting
Siehe primär capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md → Troubleshooting.
Ergänzend für den Deploy-Kontext:
ArgoCD zeigt OutOfSync, synct aber nicht automatisch
ssh [email protected] \
'sudo kubectl -n argocd get application cloudflared -o yaml | grep -A5 syncPolicy'
Sollte automated: {prune: true, selfHeal: true} zeigen (kommt aus dem
Root-ApplicationSet). Falls nicht, manuellen Sync erzwingen (siehe oben).
ConfigMap-Änderung kommt nicht im Pod an
Der Helm-Chart triggert Rollouts über eine Checksum-Annotation auf dem
Deployment. Falls ein Rollout dennoch hängt:
ssh [email protected] \
'sudo kubectl -n cloudflared rollout restart deployment/cloudflared'
ssh [email protected] \
'sudo kubectl -n cloudflared rollout status deployment/cloudflared'
kubectl -n cloudflared get pods zeigt Pending
Meist Ressourcenmangel oder ein Problem mit dem SealedSecret (Pod kann
das Secret-Volume nicht mounten, weil cloudflared-credentials noch
nicht existiert):
ssh [email protected] \
'sudo kubectl -n cloudflared get sealedsecret,secret'
Falls das Secret fehlt, obwohl die SealedSecret existiert: Der
Sealed-Secrets-Controller konnte den Ciphertext nicht entschlüsseln
(falscher Namespace/Name beim kubeseal-Aufruf in capulus-core/e-externe-erreichbarkeit/e0000-cloudflare-tunnel.md, Schritt 3) —
Ciphertext neu erzeugen und values.yaml korrigieren.
Rollback
Wie jede andere App per Git-Revert:
git log --oneline -- argocd/apps/tech/cloudflared
git revert <commit-hash>
git push
ArgoCD synct den vorherigen Zustand automatisch zurück. Um den kompletten
Tunnel vorübergehend zu deaktivieren, ohne ihn zu löschen, reicht es, das
ArgoCD-App-Verzeichnis nicht zu ändern und stattdessen replicaCount: 0
zu setzen und zu pushen — die DNS-Einträge bleiben bestehen, aber es
antwortet niemand mehr.