Vom Laptop ist die Datenbank erreichbar, aus dem Pod bleibt die Verbindung hängen. Dabei steht der Tunnel, die Route ist angekündigt und der Proxy läuft. Die Ursache kann im Zusammenspiel von Kubernetes-Service, Headscale-Policy, Routenfreigabe und DNS liegen. Keines dieser Systeme prüft jedoch allein, ob alle Voraussetzungen für die Verbindung erfüllt sind.
Für diese Lücke entwickle ich tailnet-operator. Er bildet Verbindungen zwischen Kubernetes und einem Headscale-Tailnet als eigene Ressourcen ab. Damit bekommt ein Namespace einen stabilen Service für ein entferntes Ziel oder eine Anwendung einen privaten HTTPS-Eingang. Die zugehörigen Identitäten, Freigaben und Statusinformationen entstehen aus derselben Deklaration.
Der Operator nutzt die vorhandene VPN-Infrastruktur und übernimmt die Betriebslogik, die bisher zwischen Kubernetes und Headscale von Hand gepflegt werden musste.
Das Problem ist nicht der Tunnel#
Ein einzelner Tailscale-Client im Pod ist schnell gestartet, und auch ein vorgeschaltetes socat lässt sich leicht ergänzen. Der Aufwand wächst, sobald mehrere Anwendungen solche Verbindungen brauchen und sie dauerhaft betrieben werden sollen.
Eine Anwendung soll eine Datenbank an einem anderen Standort erreichen. Eine zweite braucht einen internen HTTPS-Dienst mit unverändertem Hostnamen. Ein Dashboard soll ausschließlich für eine bestimmte Tailnet-Gruppe erreichbar sein. Dazu kommen Zertifikate, Namespaces, Neustarts und die Frage, wer nach einem Umbau die alte Berechtigung wieder entfernt.
Der eigentliche Aufwand verteilt sich dann über mehrere Ebenen:
| Ebene | Die Frage dahinter |
|---|---|
| Kubernetes | Welcher Service zeigt auf welchen Proxy? Welche Pods dürfen ihn erreichen? |
| Tailnet-Identität | Unter welchem Tag und Namen tritt der Proxy auf? |
| Routing | Wird das Zielnetz angekündigt und ist die Route genehmigt? |
| Zugriff | Darf genau diese Identität genau dieses Ziel erreichen? |
| DNS und TLS | Welcher Name zeigt wohin, und zu welchem Namen passt das Zertifikat? |
| Betrieb | Welche dieser Voraussetzungen fehlt gerade? |
Mein früheres Tailnet-Gateway hat einen wichtigen Teil davon gelöst. Mit wachsender Nutzung musste ich aber immer mehr Zusammenhänge zwischen gemeinsam genutzten Proxys, einzelnen Policy-Zeilen und manuellen Konventionen im Blick behalten.
Daraus entstand die Idee, die gewünschte Verbindung selbst zum verwalteten Objekt zu machen. So lassen sich ihre Voraussetzungen gemeinsam beschreiben und abgleichen.
Drei Ressourcen statt einer Sammlung von Sonderfällen#
Das Modell besteht aus drei Custom Resources:
| Ressource | Bedeutung |
|---|---|
Tailnet | Die administrative Bindung an Headscale: API-Zugang, DNS-Konfiguration, Policy-Basis und Defaults |
TailnetEgress | Eine eigene Identität für Verbindungen aus dem Cluster zu entfernten TCP-Zielen |
TailnetIngress | Eine eigene Identität, über die Tailnet-Teilnehmer ausgewählte Cluster-Services erreichen |
Ein Tailnet ist clusterweit. Egress-Ressourcen liegen im Operator-Namespace; sie benennen explizit ihre Consumer-Namespaces. Ingress-Ressourcen können bei den Anwendungen liegen. Im Lab gibt es daneben administrative Ingress-Ressourcen, die Backends in anderen Namespaces referenzieren.
Aus dieser Verbindungsbeschreibung erzeugt der Operator die Datenebene. Die Anwendungen brauchen dadurch keinen eigenen Tailscale-Sidecar.
Control Plane und Datenverkehr bleiben getrennt#
Der in Go geschriebene Operator spricht mit Kubernetes und der Headscale-API. Er erzeugt Deployments, Services, NetworkPolicies und Agent-Konfiguration und gleicht deren Zustand ab.
Für den eigentlichen Datenverkehr gibt es pro Ingress- oder Egress-Ressource einen eigenen Userspace-tsnet-Agenten. Der Reconciler ist nicht Teil dieses Datenpfads.
Für die Anwendung bleibt ein Egress-Ziel eine normale TCP-Verbindung zu einem Kubernetes-Service. Sie muss weder SOCKS sprechen noch einen VPN-Client bedienen. Die Agenten selbst benötigen kein NET_ADMIN und kein /dev/net/tun.
Diese Eigenschaften gelten für die Datenebene der Agenten, nicht für die gesamte Tailnet-Infrastruktur. Für den Zugriff auf ein entferntes LAN muss weiterhin ein geeigneter Router dessen Netz ankündigen. Im Lab übernimmt das eine separate Gateway-/Subnet-Router-Schicht.
Der Operator selbst benötigt weitreichendes Vertrauen, weil er die Policy schreiben und Arbeits-API-Schlüssel verwalten darf. Dabei ist auch zwischen der Verwendung eines Schlüssels und seinen Berechtigungen zu unterscheiden: Der Operator liest den Bootstrap-Schlüssel, ohne ihn zu verändern. Das beschränkt den Schlüssel aber nicht auf lesende Headscale-Aktionen.
Verwendung: erst die administrative Grundlage#
Vor der ersten Anwendung müssen Headscale, der API-Zugang, eine Basis-Policy und die DNS-Einbindung stehen. Für automatische HTTPS-Zertifikate kommt cert-manager mit einem passenden Issuer hinzu.
Als Einstieg eignet sich DryRun. Der Operator berechnet die Policy, schreibt sie aber noch nicht nach Headscale. So kann ich prüfen, wie sich die Ressourcen auf die Zugriffsregeln meines Netzes auswirken würden, bevor ich diese Änderungen freigebe.
<API-GRUPPE> ist bewusst ein Platzhalter und muss durch die API-Gruppe der installierten CRDs ersetzt werden. Namen, Dokumentationsadressen und Voraussetzungen sind ebenfalls anzupassen; die Blöcke sind kein vollständiger Bootstrap. 1apiVersion: <API-GRUPPE>/v1alpha1
2kind: Tailnet
3metadata:
4 name: demo
5spec:
6 server: https://control.example.net
7 apiSecretRef:
8 name: headscale-bootstrap
9 key: apiKey
10 dns:
11 hostsConfigMap: tailnet-hosts
12 ingressNameTemplate: "{name}.{namespace}.lab.example.net"
13 ingressAliasTemplate: "{name}.lab.example.net"
14 defaults:
15 tls:
16 issuerRef:
17 name: apps-ca
18 kind: ClusterIssuer
19 policy:
20 baseConfigMap: tailnet-policy
21 mode: DryRun
22 tagOwners: ["group:platform"]
23 routeApprovers: ["tag:router"]
24 ingressSourceAllowlist: ["group:team-a"]
Die referenzierten Gruppen, Secrets, ConfigMaps und der Issuer müssen existieren. DryRun erteilt die berechneten Berechtigungen noch nicht. Erst nach Prüfung des Ergebnisses wird die verantwortliche Installation auf Apply umgestellt.
Installiert wird der Operator über sein Helm-Chart. Im Lab sind Chart-Version und Image-Digest gepinnt; Flux hält die Installation und die Ressourcen im gewünschten Zustand. Damit bleibt nachvollziehbar, welche Version installiert ist, und ein Update erfolgt bewusst statt durch das unbemerkte Laden der neuesten Version.
Beispiel 1: ein entferntes Ziel wird ein normaler Service#
Angenommen, ein Namespace braucht PostgreSQL an einem anderen Standort und eine dortige HTTPS-API. Dann beschreibt eine Egress-Ressource die Ziele und die zugelassenen Consumer:
1apiVersion: <API-GRUPPE>/v1alpha1
2kind: TailnetEgress
3metadata:
4 name: team-a
5 namespace: tailnet-system
6spec:
7 tailnetRef:
8 name: demo
9 consumerNamespaces: [team-a]
10 targets:
11 - name: remote-db
12 address: 192.0.2.10
13 port: 5432
14 - name: remote-api
15 address: 198.51.100.20
16 port: 443
17 aliases: [api.site.example.net]
Für das erste Ziel entsteht ein Service namens remote-db im Operator-Namespace. Die Anwendung verbindet sich beispielsweise mit:
1remote-db.tailnet-system.svc.cluster.local:5432
Dahinter übernimmt der Agent den Weg durch das Tailnet. Die Consumer-Namespace-Liste begrenzt über NetworkPolicies, welche Pods diesen Zugang nutzen dürfen. Das setzt ein CNI voraus, das diese Regeln tatsächlich durchsetzt.
Die Dokumentationsadressen im Beispiel stehen für Ziele hinter einem entsprechend konfigurierten Router. Dieser muss das Zielnetz ankündigen; das Anlegen des Services allein stellt noch keine Verbindung dorthin her.
HTTPS braucht mehr als eine erreichbare IP#
Beim zweiten Ziel ist der Alias interessant. Würde die Anwendung statt api.site.example.net einfach einen beliebigen Service-Namen benutzen, könnten TLS-SNI, Zertifikatsname oder HTTP-Host nicht mehr zum entfernten Dienst passen.
Der Alias lässt den ursprünglichen Namen auf den lokalen Egress-Service zeigen. Der Client verwendet weiter die erwartete URL, und der TCP-Pfad bleibt transparent. Der Operator muss das TLS der entfernten Anwendung dafür nicht terminieren.
Für die Namensauflösung braucht es eine zusätzliche Einbindung, denn der Operator ist kein DNS-Server. Er rendert die benötigten Einträge in eine ConfigMap. CoreDNS beziehungsweise die zuständige DNS-Infrastruktur muss diese Einträge ausliefern, damit der Alias tatsächlich aufgelöst wird.
Im Lab ist derzeit ein begrenzter Management-Endpunkt als Egress-Anwendungsfall belegt, der zur Evaluation und für Regressionstests dient. Die externe Datenbank oben zeigt ein unterstütztes Nutzungsmuster; sie ist keine produktiv betriebene Lab-Datenbank.
Beispiel 2: zwei Weboberflächen, ein privater HTTPS-Eingang#
In der Gegenrichtung bekommt ein Dienst einen Eingang aus dem Tailnet. mode: http bedeutet dabei: HTTPS wird am Agenten terminiert, dahinter folgt HTTP oder ausdrücklich konfiguriertes HTTPS zum Backend.
1apiVersion: <API-GRUPPE>/v1alpha1
2kind: TailnetIngress
3metadata:
4 name: portal
5 namespace: team-a
6spec:
7 tailnetRef:
8 name: demo
9 allowFrom: ["group:team-a"]
10 exposes:
11 - name: web
12 dnsLabel: portal
13 alias: true
14 mode: http
15 port: 443
16 backend:
17 service: frontend
18 port: 8080
19 - name: admin
20 dnsLabel: admin
21 mode: http
22 port: 443
23 backend:
24 service: admin
25 port: 8443
26 tls:
27 serverName: admin.team-a.svc.cluster.local
28 caConfigMapRef:
29 name: backend-ca
30 key: ca.crt
31 timeouts:
32 request: 600s
33 backendRequest: 60s
Mit dem oben gezeigten Namensschema entstehen portal.team-a.lab.example.net und admin.team-a.lab.example.net. Der erste Eintrag erhält zusätzlich den kurzen Alias portal.lab.example.net.
Beide Namen teilen eine Tailnet-Identität und deren Zugriffsregeln. Virtual Hosting bündelt damit Dienste mit gleichen Berechtigungen auf einem Agenten. Dienste mit unterschiedlichen Berechtigungsgruppen gehören dagegen in getrennte Ressourcen, denn zwei Hostnamen bilden keine getrennten Sicherheitsgrenzen.
Ein Zertifikat deckt die HTTP-Namen und Aliasse derselben Ressource ab. Es kann aus einem vorhandenen TLS-Secret kommen oder über cert-manager erzeugt werden. Passen Zertifikat und Konfiguration nicht zusammen, darf der Agent nicht still auf Klartext ausweichen.
Backend-TLS ist eine zweite Prüfung#
Das öffentliche beziehungsweise Tailnet-seitige Zertifikat beantwortet nur die Frage, ob der Client mit dem richtigen Ingress spricht. Es sagt nichts darüber, ob der Ingress anschließend das richtige Backend erreicht.
Deshalb hat backend.tls eine eigene Vertrauenskette. Servername und CA-Bundle werden explizit angegeben, damit der Agent die HTTPS-Verbindung zum Backend prüfen kann. Ein Fallback ohne Zertifikatsprüfung ist nicht vorgesehen.
Auch die Zeitbudgets für den gesamten Request und die Backend-Anfrage werden getrennt festgelegt. So lassen sich längere Uploads und das Warten auf die Backend-Antwort bewusst begrenzen. Diese Optionen bilden jedoch nicht zwangsläufig jeden Timeout eines vorherigen Proxys eins zu eins ab. Insbesondere haben etablierte WebSocket-Verbindungen einen eigenen Lebenszyklus.
Policy nicht nebenbei mitschreiben, sondern besitzen#
Bei der Entwicklung musste ich vor allem klären, wem die Headscale-Policy gehört. Ohne eindeutige Zuständigkeit können mehrere Beteiligte ihre Änderungen gegenseitig überschreiben.
Mein Modell verwendet eine von Menschen gepflegte Basis in Git. Sie enthält Gruppen, grundlegende Regeln und Policy-Tests. Auf dieser Grundlage ergänzt der Operator aus den Custom Resources unter anderem:
- Eigentümer der benötigten Tags;
- automatische Routenfreigaben für geeignete IP-Ziele;
- TCP-Grants zu Egress-Zielen;
- Ingress-Grants aus
allowFrom.
Die administrative ingressSourceAllowlist begrenzt, welche Quellen eine Ingress-Ressource überhaupt anfordern darf. Eine Anwendung soll nicht einfach durch ein großzügiges allowFrom die Plattformregeln umgehen können.
Pro Headscale-Server darf genau eine Installation die Policy schreiben. Mehrere Cluster können nicht unabhängig jeweils „ihren kleinen Teil“ als vollständige Policy hochladen und darauf hoffen, dass die Teile erhalten bleiben. Apply bedeutet Ownership des gerenderten Gesamtdokuments, nicht kooperatives Patchen durch beliebig viele Writer.
Manuelle Änderungen am laufenden Headscale-Dokument sind deshalb ebenfalls kein dauerhafter Konfigurationsweg. Der nächste Abgleich kann sie überschreiben. Gewollte Änderungen gehören in die Basis oder in die deklarativen Ressourcen.
Wird eine neue Policy abgelehnt, bleibt die bisherige aktiv. Damit wird keine Freigabe nur teilweise angewendet. Der Status muss allerdings erkennen lassen, dass die geänderte Ressource noch nicht erfolgreich wirksam ist.
Für DNS-Namen als Egress-Ziele erzeugt der Operator außerdem nicht automatisch dieselben Ziel-Grants wie für IP-Ziele. Die passenden Berechtigungen müssen in der Basis vorhanden sein.
Status ist hier kein dekoratives Extra#
Ein Pod kann gesund sein, obwohl die Verbindung durch ihn nicht funktioniert. Bei Netzproblemen hilft „Deployment available“ deshalb nur begrenzt weiter.
Der Operator unterscheidet mehrere Ursachen, die von außen sonst alle wie ein Timeout aussehen:
| Zustand oder Reason | Was er mir sagt |
|---|---|
NotAdvertised | Für das Ziel fehlt eine passende angekündigte Route. |
NotApproved | Die Route ist angekündigt, aber nicht genehmigt. |
NoGrant | Die genehmigte Route fehlt in der Sicht dieses Knotens; eine Zugriffsfreigabe fehlt. |
ProbeFailed | Der Agent konnte nicht belastbar abgefragt werden. |
PolicyDenied | Die angeforderte Quelle verletzt die administrative Allowlist. |
DNSNameConflict | Ein anderer Besitzer beansprucht den Namen bereits. |
TLSCertificatePending | Die Zertifikatsausstellung ist noch nicht abgeschlossen. |
Anhand dieser Statusinformationen kann ich die Fehlersuche eingrenzen:
1kubectl get tailnet,tailnetegress,tailnetingress -A
2kubectl -n tailnet-system describe tailnetegress team-a
3kubectl -n team-a describe tailnetingress portal
Diese Conditions gehören zusammen mit Prometheus-Metriken und den mitgelieferten Monitoring-Regeln zum Produktkern. Sie zeigen, welche Voraussetzung noch fehlt, und helfen dadurch auch im laufenden Betrieb.
Ready ist kein vollständiger Ende-zu-Ende-Test. Ein gültiges Zertifikat am Agenten beweist nicht, dass ein fremder Client der CA vertraut. Ein erreichbares Backend beweist nicht, dass Split-DNS auf jedem Client richtig eingerichtet ist. Wo der Operator etwas nicht prüfen kann, muss diese Beobachtungsgrenze sichtbar bleiben.Was davon bereits im Lab verwendet wird#
Die Beispiele sind keine reine API-Demo. Im öffentlichen GitOps-Baum ist Version v0.6.0 mit mehreren realen Anwendungen eingebunden:
- Kubernetes- und Talos-API werden als getrennte TCP-Eingänge veröffentlicht. Transportzugang ersetzt dabei weder Kubernetes-RBAC noch Talos-Clientidentitäten.
- Grafana, Prometheus, Alertmanager und Pyrra teilen einen HTTPS-Agenten mit vier Virtual Hosts. Da sie dieselbe Zugriffsgruppe haben, können sie unter getrennten Namen einen Agenten statt vier fast identischer Proxy-Deployments nutzen.
- Garage S3 und die Administrationsoberfläche verwenden verifiziertes HTTPS auch zum Backend. Gerade bei S3 muss der Proxy außerdem Nutzdaten unverändert transportieren.
- Paperless und ZeroClaw besitzen eigene HTTPS-Eingänge mit bewusst längeren Request-Budgets.
- ZNC und Syncthing verwenden ebenfalls geprüfte Backend-TLS-Verbindungen; weitere Dashboards hängen am gleichen Ressourcenmodell.
„Verwendet“ bezeichnet hier den veröffentlichten Konfigurations- und dokumentierten Migrationsstand, nicht eine frische Live-Prüfung jedes Endpunkts während des Schreibens.
Die bisherigen Zugänge wurden schrittweise abgelöst. Zuerst kamen neue Eingänge hinzu, dann folgten anwendungsspezifische Abnahmeschritte. Erst danach wurden die alten Routen entfernt. Bei Paperless müssen etwa Anmeldung und Originaldownload funktionieren, bei S3 die Objektbytes unverändert bleiben. Auch eine Monitoring-Oberfläche muss mehr liefern als ihre anonyme Loginseite.
Ein grünes Ready allein deckt diese anwendungsspezifischen Prüfungen nicht ab.
Die Entwicklung: immer weniger Wissen außerhalb der Ressource#
Der Weg zum heutigen Stand verlief in nachvollziehbaren Schritten:
- TCP-Pfade in beide Richtungen: zunächst die grundlegende Verbindung und ihre Identität.
- DNS-Rendering: Namen nicht mehr getrennt von ihren Services und Tailnet-Knoten pflegen.
- Policy Ownership: Tags und Freigaben aus derselben Absicht ableiten, inklusive Nachholen verpasster Routenfreigaben.
- Native HTTPS-Eingänge: Zertifikate und HTTP-Verarbeitung direkt am Agenten statt eines zusätzlichen gemeinsamen Umwegs.
- Backend-TLS und Zeitbudgets: reale Anwendungen brauchen mehr als einen simplen Reverse Proxy.
- Virtual Hosts in v0.6.0: mehrere Namen bündeln, wenn Identität und Berechtigungen tatsächlich zusammengehören.
Eine besonders lehrreiche Korrektur betraf die automatische Dekomprimierung von Backend-Antworten. Sie musste unterbleiben, damit die übertragenen Bytes unverändert bleiben. Was bei einem Browser als transparente Transformation harmlos wirken kann, verletzt bei einem Objektspeicher die Anforderungen an den Transport.
Hier hilft mir das Lab als Entwicklungsumgebung: Mit echten Diensten werden Anforderungen sichtbar, die ein Echo-Server hinter der neuen API nicht abbildet.
Wofür ich ihn heute einsetzen würde — und wofür nicht#
Der passende Einsatzfall ist eine Kubernetes-Plattform mit Headscale, die ausgewählte Dienste zwischen Cluster und Tailnet sauber verbinden will. Der beschriebene Release setzt Kubernetes ab 1.31, Headscale 0.29.x und ein NetworkPolicy-fähiges CNI voraus.
Er ist dagegen kein vollständiger Ersatz für alle Netzwerkkomponenten:
- Kein allgemeiner Manager für Headscale und die gesamte Router-Infrastruktur.
- Kein Pod-Mesh zwischen allen Clustern.
- Kein UDP-Service-Forwarding in diesem Funktionsumfang.
- Keine automatische Anwendungsanmeldung oder OIDC-Schicht.
- Keine behauptete harte Isolation gegeneinander bösartiger Mandanten.
- Keine Garantie unterbrechungsfreier Upgrades: Agenten laufen als Einzelinstanzen mit
Recreate.
Im Vergleich zum früheren gemeinsamen Gateway wird Verantwortung anders zugeschnitten, nicht jede Abhängigkeit beseitigt. DNS, Routing, Zertifikatsvertrauen und Anwendungsautorisierung bleiben reale Aufgaben. Der Operator macht ihren Zusammenhang beschreibbar und prüfbarer.
Der eigentliche Gewinn#
Mit tailnet-operator bekommt eine Verbindung einen Besitzer, eine deklarierte Absicht und einen erklärbaren Zustand. Das erleichtert sowohl Änderungen als auch die Fehlersuche.
Bei einem Verbindungsausfall möchte ich an der Ressource erkennen, ob die Route fehlt, eine Freigabe abgelehnt wurde oder das Zertifikat noch nicht bereitsteht. Dafür sollte ich nicht erst eine zusätzliche Ausnahme in einem von vier Repositories suchen müssen.
So wird die Verbindung zu einem Teil der Plattform, den ich mit denselben Werkzeugen beschreiben, prüfen und versionieren kann wie die Anwendung selbst.
Quellenstand: Funktionsumfang des Releases v0.6.0 und die öffentliche Lab-Konfiguration Anfang Oktober 2026. Die praktischen Integrationen stehen im Lab-Repository
unter applications/tailscale-system/tailnet-operator/. Die beiden ergänzenden Artikel zeigen Paperless als Anwendung
und ZeroClaw als lesenden Triage-Client
.
