Traefik Gateway API richtet HTTP-Routing in Kubernetes über standardisierte Ressourcen ein: GatewayClass, Gateway und HTTPRoute ersetzen dabei nicht den Proxy, sondern beschreiben klar getrennt, wer ihn betreibt und welche Anwendung erreichbar sein soll. Dieser Leitfaden installiert die Standard-CRDs, aktiviert den Traefik-Provider und veröffentlicht einen Beispiel-Service mit TLS-Vorbereitung.

Stand: 03.11.2026

Auf einen Blick

  • Gateway API trennt Infrastruktur und Routing-Konfiguration sauber.
  • Für HTTPRoute reichen die Standard-CRDs; Experimental-CRDs sind hier nicht nötig.
  • Der Traefik-Helm-Chart aktiviert RBAC automatisch.
  • Ein Gateway akzeptiert Routen nur nach seiner Listener- und Namespace-Regel.
  • Statusbedingungen von Gateway und HTTPRoute sind der entscheidende Funktionstest.

1. Die Ausgangslage und das Ziel

Warum Gateway API statt eines weiteren Ingress-Manifests?

Mit Traefik Gateway API beschreibst du den Einstiegspunkt und die Route als getrennte Kubernetes-Objekte. Eine Plattform-Administration kann den Gateway bereitstellen, während ein Team nur seine HTTPRoute pflegt. Das folgt dem Modell der Gateway API: GatewayClass benennt die Implementierung, Gateway konfiguriert Listener und HTTPRoute leitet Anfragen an Services weiter.

Das Ziel ist eine Anwendung unter app.example.net, die Traefik über HTTPS annimmt und an einen Kubernetes-Service weiterreicht. Der Ablauf passt zu einem bestehenden Traefik-Deployment. Für die Grundlagen des Clusters hilft der Artikel Helm Charts erklärt; die Unterschiede zwischen Orchestrierung und Containern ordnet Kubernetes vs. Docker Swarm ein.

Architektur von Traefik Gateway API mit Client, Traefik, Gateway, HTTPRoute und Kubernetes-Service.
Der Gateway ist der freigegebene Eintrittspunkt; die HTTPRoute verbindet Host und Service.

Was dieser Leitfaden bewusst nicht macht

Er ersetzt keine produktive Ingress-Migration auf einen Schlag und richtet keine Zertifizierungsstelle ein. Deshalb bleibt die Konfiguration klein: ein Gateway, ein Namespace und eine Route. Sobald dieser Pfad funktioniert, kannst du weitere Hosts ergänzen. Die Standard-CRDs enthalten laut Gateway-API-Dokumentation unter anderem GatewayClass, Gateway, HTTPRoute und ReferenceGrant.

2. Voraussetzungen und Architektur

Du brauchst einen erreichbaren Kubernetes-Cluster, kubectl, Helm und einen Traefik-Release mit LoadBalancer- oder NodePort-Zugang. Der aktuelle Traefik-Chart nennt Kubernetes ab 1.30 als Voraussetzung. Prüfe zunächst Kontext und Nodes, denn ein Manifest im falschen Cluster ist kein hilfreicher Test.

Dieser Befehl zeigt den aktiven Kontext und die Nodes.

kubectl config current-context
kubectl get nodes

Erfolgreich ist der Schritt, wenn der erwartete Kontext erscheint und die Nodes den Status Ready tragen.

Teil 1 – Namensräume und Verantwortlichkeiten planen

Lege den Gateway in einen eigenen Infrastruktur-Namespace. Die Demo-Anwendung kommt dagegen in demo. Dadurch bleibt sichtbar, welche Objekte den externen Eintrittspunkt steuern. Der Listener akzeptiert später Routen aus allen Namespaces; in einer Mandantenumgebung solltest du diese Freigabe enger fassen.

Mit diesem Manifest erzeugst du die beiden Namespaces.

apiVersion: v1
kind: Namespace
metadata:
  name: traefik-system
---
apiVersion: v1
kind: Namespace
metadata:
  name: demo

Nach dem Anwenden müssen beide Namen in der Namespace-Liste auftauchen.

Wende die Datei als namespaces.yaml an.

kubectl apply -f namespaces.yaml
kubectl get namespace traefik-system demo

Die Ausgabe zeigt für beide Objekte Active.

3. Gateway API und Traefik aktivieren

Teil 2 – Die Standard-CRDs installieren

Traefik Gateway API kann HTTPRoute aus dem Standard-Channel verarbeiten. Traefik dokumentiert dafür die Standard-CRDs; die Gateway-API-Installation empfiehlt server-side apply. Verwende für diesen HTTP-Leitfaden nicht den Experimental-Channel: Traefik weist ausdrücklich darauf hin, dass experimentalChannel ohne passende Experimental-CRDs verhindert, dass der Gateway-Provider startet.

Dieser Befehl installiert die Standard-CRDs in der von der Gateway API veröffentlichten Version.

kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.3/standard-install.yaml

Danach müssen die zentralen API-Ressourcen vom API-Server erkannt werden.

Prüfe das mit der API-Resource-Liste.

kubectl api-resources --api-group=gateway.networking.k8s.io

Erwartet werden mindestens gatewayclasses, gateways und httproutes. Fehlt eine Ressource, darfst du noch keine Route anwenden.

Traefik per Helm konfigurieren

Der Helm-Chart verwaltet laut Traefik die notwendigen RBAC-Regeln. Aktiviere daher den Gateway-Provider in den Chart-Werten, statt Traefik nebenbei mit einer unvollständigen statischen Konfiguration zu starten. Der Provider beobachtet ohne Namespace-Einschränkung alle Namespaces; diese einfache Demo setzt deshalb nur ein kontrolliertes Testprojekt ein.

Die Datei values-gateway.yaml schaltet den Provider ein.

providers:
  kubernetesGateway:
    enabled: true

Installiere oder aktualisiere damit den Release. Ersetze traefik nur, wenn dein Release anders heißt.

helm upgrade --install traefik traefik/traefik \
  --namespace traefik-system \
  --create-namespace \
  --values values-gateway.yaml

Helm meldet einen erfolgreichen Release; anschließend müssen die Traefik-Pods bereit sein. Besteht bereits ein Release mit anderen Werten, sichere dessen Werte vorher mit helm get values.

GatewayClass kontrollieren

Ein Controller stellt eine GatewayClass bereit. Welche Klasse verfügbar ist, entscheidet die Installation; daher wird kein Klassenname geraten. Liste zuerst die Klassen und übernimm dann den Namen, dessen Controller Traefik zugeordnet ist.

Dieser Befehl zeigt die verfügbaren Klassen und ihren Controller-Namen.

kubectl get gatewayclass -o wide
kubectl get pods -n traefik-system

Die Pods sollen Running und READY zeigen. Notiere den tatsächlichen Klassennamen für das nächste Manifest.

4. Gateway und HTTPS-Listener anlegen

Teil 3 – Den Eintrittspunkt deklarieren

Ein Gateway bindet Listener an eine GatewayClass. Der Hostname am Listener begrenzt, welche Hostnamen passende Routen verwenden dürfen. Das ist wichtig: Ein HTTPRoute-Objekt allein öffnet keinen Port. Das Gateway ist die Infrastrukturfreigabe, die Route ist die Anwendungsfreigabe.

Dieses Manifest erzeugt einen HTTP- und einen HTTPS-Listener. Ersetze Klassenname, Domain und Secretname durch deine Werte.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public-gateway
  namespace: traefik-system
spec:
  gatewayClassName: <TRAEFIK-GATEWAYCLASS>
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    protocol: HTTPS
    port: 443
    hostname: app.example.net
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: app-example-net-tls
    allowedRoutes:
      namespaces:
        from: All

Der HTTPS-Listener benötigt ein TLS-Secret im selben Namespace wie das Gateway. Lege es erst an, wenn Zertifikat und Schlüssel vorliegen; für eine produktive Automatisierung passt ein eigener cert-manager-Leitfaden besser als ein unkontrolliertes Hand-Zertifikat.

Wende das Gateway an und lies seinen Status aus.

kubectl apply -f gateway.yaml
kubectl get gateway public-gateway -n traefik-system
kubectl describe gateway public-gateway -n traefik-system

Erfolgreich ist der Schritt erst, wenn die Conditions Accepted=True und Programmed=True zeigen. Accepted bestätigt die Konfiguration; Programmed zeigt, dass der Controller sie umgesetzt hat.

Ablauf vom Anwenden der Gateway-API-CRDs bis zur Prüfung der HTTPRoute-Conditions.
Die Conditions zeigen, ob der Controller die deklarierte Konfiguration akzeptiert und programmiert hat.

5. Service und HTTPRoute veröffentlichen

Teil 4 – Eine testbare Anwendung bereitstellen

Für den Nachweis genügt ein Service mit vorhandenem Endpoint. Verwende im produktiven Fall deinen eigenen Deployment- und Service-Namen. Die Route referenziert nur den Service-Port, nicht einzelne Pods; deshalb bleiben Rollouts und wechselnde Pod-IP-Adressen vom Routing entkoppelt.

Dieses Beispiel erzeugt Deployment und Service für eine einfache HTTP-Antwort.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
      - name: whoami
        image: traefik/whoami
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: whoami
  namespace: demo
spec:
  selector:
    app: whoami
  ports:
  - port: 80
    targetPort: 80

Nach kubectl apply -f whoami.yaml muss der Service mindestens einen Endpoint besitzen.

Die HTTPRoute bindet den Host an das Gateway und leitet den Pfad / weiter.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: whoami
  namespace: demo
spec:
  parentRefs:
  - name: public-gateway
    namespace: traefik-system
    sectionName: https
  hostnames:
  - app.example.net
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: whoami
      port: 80

Die Struktur folgt dem offiziellen HTTP-Routing-Leitfaden der Gateway API. Anders als ein pauschaler Catch-all lässt der Hostname die Absicht eindeutig prüfen.

Wende Route und Anwendung an und prüfe Endpoints sowie die Route.

kubectl apply -f whoami.yaml
kubectl apply -f route.yaml
kubectl get endpoints -n demo whoami
kubectl describe httproute -n demo whoami

Bei Erfolg enthält der Service eine Endpoint-Adresse. In der HTTPRoute muss beim Parent die Condition Accepted=True erscheinen.

Die wichtigsten Stolperfallen

Gateway-Provider startet nicht

Symptom: Gateway-Objekte bleiben ohne Status. Ursache: experimentalChannel ist aktiv, aber die Experimental-CRDs fehlen. Lösung: Für HTTPRoute den Provider ohne Experimental-Option nutzen oder die passenden Experimental-CRDs bewusst installieren. Traefik dokumentiert, dass sonst der gesamte Gateway-Provider nicht startet.

HTTPRoute wird nicht akzeptiert

Symptom: Die Route existiert, aber Accepted ist nicht True. Ursache: parentRefs, Namespace, Listenername oder Hostname passen nicht zum Gateway. Lösung: kubectl describe httproute lesen und Parent, sectionName sowie Hostnamen exakt abgleichen.

Gateway zeigt keinen programmierten Zustand

Symptom: Programmed bleibt False oder fehlt. Ursache: Traefik kann die GatewayClass nicht verarbeiten oder der LoadBalancer ist noch nicht bereit. Lösung: GatewayClass, Traefik-Pods und den Traefik-Service getrennt kontrollieren.

TLS-Listener ist nicht bereit

Symptom: HTTP funktioniert, HTTPS nicht. Ursache: Das referenzierte Secret fehlt oder liegt im falschen Namespace. Lösung: Das Secret neben dem Gateway anlegen und Namen sowie certificateRefs abgleichen.

Backend liefert einen Fehler

Symptom: Die Route ist akzeptiert, die Antwort ist aber 503 oder fehlerhaft. Ursache: Der Service hat keine Endpoints oder der referenzierte Port stimmt nicht. Lösung: Service-Selector, Pod-Labels und backendRefs.port prüfen. Für Container-Grundlagen ist Docker Healthcheck einrichten eine sinnvolle Ergänzung.

Verifikation: So prüfst du, dass alles läuft

Prüfe zuerst die Ressourcenbedingungen. Dieser Befehl zeigt Gateway und Route in einer kompakten Übersicht.

kubectl get gateway -n traefik-system
kubectl get httproute -n demo
kubectl get svc,endpoints -n demo

Erwartet werden ein Gateway mit akzeptierter Programmierung, eine HTTPRoute mit akzeptiertem Parent und mindestens ein Endpoint für whoami. Danach prüfst du DNS und die echte HTTPS-Antwort vom Client aus.

Dieser Aufruf fragt den Zielhost ab.

curl -i https://app.example.net/

Bei der Demo enthält die Antwort HTTP-Status 200 und Angaben des whoami-Containers. Erhältst du einen TLS-Fehler, prüfe zuerst Secret und DNS; bei 404 stimmen typischerweise Hostname oder Listener nicht überein. Überwache danach den Proxy wie in Kubernetes Monitoring mit Grafana und Prometheus beschrieben, statt Fehler nur beim nächsten Nutzerhinweis zu entdecken.

Fazit

Traefik Gateway API macht aus externem Zugang eine nachvollziehbare Kette aus GatewayClass, Gateway, HTTPRoute und Service. Installiere zunächst nur die Standard-CRDs und aktiviere den Gateway-Provider explizit. Entscheidend sind nicht nur angewendete YAML-Dateien, sondern die Conditions von Gateway und Route sowie ein realer HTTPS-Abruf. Danach kannst du das Muster pro Anwendung wiederholen und Namespace-Grenzen gezielt verschärfen.

Quellen

Häufige Fragen

Was ist der Unterschied zwischen Gateway API und Ingress?

Gateway API teilt Infrastruktur, Listener und Routen in eigene Ressourcen auf. Dadurch lassen sich Verantwortlichkeiten und Berechtigungen klarer trennen als bei einem einzelnen Ingress-Objekt.

Brauche ich für Traefik Gateway API den Experimental-Channel?

Nein, für Gateway, GatewayClass und HTTPRoute reicht der Standard-Channel. Experimental-CRDs sind erst für Ressourcen wie TCPRoute oder TLSRoute nötig.

Warum wird meine HTTPRoute nicht akzeptiert?

Prüfe parentRefs, Namespace, sectionName und Hostname gegen den Listener des Gateways. kubectl describe httproute zeigt die Conditions und den Ablehnungsgrund.

Wo muss das TLS-Secret für einen Gateway liegen?

Das in certificateRefs referenzierte Secret muss im selben Namespace wie der Gateway liegen. Namen und Referenz müssen exakt übereinstimmen.

Wie prüfe ich Traefik Gateway API?

Prüfe zuerst Accepted- und Programmed-Conditions bei Gateway und HTTPRoute. Danach rufst du den konfigurierten HTTPS-Host von außerhalb des Clusters ab.

Related Posts: