Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Von Ingress zur Gateway API

Ziel: Du kennst das Ressourcenmodell, hast Envoy Gateway installiert und liest Conditions wie ein Profi. · Dauer: ca. 45 min · Voraussetzung: Tag 0

Briefing

  • Ingress kennt eine Ressource für alles. Alles, was über Host und Pfad hinausgeht, landet in herstellerspezifischen Annotationen.
  • Die Gateway API trennt Rollen: GatewayClass (Infrastruktur-Anbieter), Gateway (Plattform-Team), Routes (App-Teams).
  • Sie ist ein Satz CRDs, kein Teil von Kubernetes selbst. Version und Channel (Standard oder Experimental) stehen als Annotation an jeder CRD.
  • Jede Ressource meldet in status.conditions, ob sie akzeptiert und umgesetzt wurde. Fehlt der Status, fühlt sich kein Controller zuständig.
 Infrastruktur-Anbieter   GatewayClass "eg"        (cluster-weit)
          │
 Plattform-Team           Gateway "web" (ns infra)  Listener: Port, Protokoll, TLS
          │  parentRefs
 App-Teams                HTTPRoute (ns shop) ──► Service shop-v1 / shop-v2
                          GRPCRoute (ns payments) ──► Service payments

Drill 1: Ingress ohne Controller

cd ~/gw-lab/tag01
cat > ingress-shop.yaml <<'EOF'
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: shop
  namespace: shop
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: shop.gw.localtest.me
      http:
        paths:
          - path: /v2
            pathType: Prefix
            backend:
              service:
                name: shop-v2
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: shop-v1
                port:
                  number: 80
EOF
kubectl apply -f ingress-shop.yaml
kubectl -n shop get ingress
kubectl get ingressclass

Erwartet:

ingress.networking.k8s.io/shop created
NAME   CLASS    HOSTS                  ADDRESS   PORTS   AGE
shop   <none>   shop.gw.localtest.me             80      0s
No resources found

Kein Controller, keine Adresse, keine Fehlermeldung. Die Annotation nginx.ingress.kubernetes.io/rewrite-target versteht nur ingress-nginx – mit Traefik oder HAProxy wäre sie wirkungslos. Genau dieses Problem löst die Gateway API: Rewrite, Header, Gewichte und Timeouts sind Teil der Spezifikation.

Ingress Gateway API Wem gehört es?
IngressClass GatewayClass Infrastruktur-Anbieter
(im Controller versteckt) Gateway mit Listenern Plattform-Team
Ingress-Regeln HTTPRoute, GRPCRoute, TLSRoute … App-Team
Annotationen Filter, Policies App- bzw. Plattform-Team

Fortschritt speichern? Kostenlos registrieren

Drill 2: Noch keine Gateway API im Cluster

kubectl api-resources --api-group=gateway.networking.k8s.io
kubectl get crd | grep -c gateway.networking.k8s.io

Erwartet:

NAME   SHORTNAMES   APIVERSION   NAMESPACED   KIND
0

Kubernetes bringt die Gateway API nicht mit. Die CRDs installierst du selbst – oder sie kommen mit dem Controller, wie gleich bei Envoy Gateway.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Envoy Gateway installieren

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.2 \
  -n envoy-gateway-system --create-namespace
kubectl wait --timeout=5m -n envoy-gateway-system \
  deployment/envoy-gateway --for=condition=Available

Erwartet (gekürzt):

Pulled: docker.io/envoyproxy/gateway-helm:v1.9.2
NAME: eg
NAMESPACE: envoy-gateway-system
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
...
deployment.apps/envoy-gateway condition met
helm list -n envoy-gateway-system
kubectl -n envoy-gateway-system get pods

Erwartet (gekürzt):

NAME  NAMESPACE             REVISION  STATUS    CHART                APP VERSION
eg    envoy-gateway-system  1         deployed  gateway-helm-v1.9.2  v1.9.2
NAME                             READY   STATUS      RESTARTS   AGE
eg-gateway-helm-certgen-9hmj4    0/1     Completed   0          30s
envoy-gateway-75b559cc4c-8xn4q   1/1     Running     0          27s

Der certgen-Job erzeugt die TLS-Zertifikate, mit denen der Controller per xDS mit den Envoy-Proxys spricht. Die Proxys selbst entstehen erst, wenn es ein Gateway gibt (Tag 2).

Achtung: Das Chart ist ein OCI-Artefakt. helm repo add gibt es hier nicht; die Version gehört immer mit --version gepinnt.

Fortschritt speichern? Kostenlos registrieren

Drill 4: CRDs, Versionen und Channels

kubectl api-resources --api-group=gateway.networking.k8s.io \
  | awk '{printf "%-20s %-30s %s\n", $1, $(NF-2), $NF}'

Erwartet:

NAME                 APIVERSION                     KIND
backendtlspolicies   gateway.networking.k8s.io/v1   BackendTLSPolicy
gatewayclasses       gateway.networking.k8s.io/v1   GatewayClass
gateways             gateway.networking.k8s.io/v1   Gateway
grpcroutes           gateway.networking.k8s.io/v1   GRPCRoute
httproutes           gateway.networking.k8s.io/v1   HTTPRoute
listenersets         gateway.networking.k8s.io/v1   ListenerSet
referencegrants      gateway.networking.k8s.io/v1   ReferenceGrant
tcproutes            gateway.networking.k8s.io/v1   TCPRoute
tlsroutes            gateway.networking.k8s.io/v1   TLSRoute
udproutes            gateway.networking.k8s.io/v1   UDPRoute

Alles v1. Mit Gateway API v1.5 kamen TLSRoute, ListenerSet und ReferenceGrant v1 in den Standard-Channel, mit v1.6 TCPRoute und UDPRoute.

C='CRD:.metadata.name'
C+=',CHANNEL:.metadata.annotations.gateway\.networking\.k8s\.io/channel'
C+=',BUNDLE:.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version'
kubectl get crd -o custom-columns="$C" | grep -E 'CRD|networking'

Erwartet:

CRD                                                   CHANNEL        BUNDLE
backendtlspolicies.gateway.networking.k8s.io          experimental   v1.6.1
gatewayclasses.gateway.networking.k8s.io              experimental   v1.6.1
gateways.gateway.networking.k8s.io                    experimental   v1.6.1
grpcroutes.gateway.networking.k8s.io                  experimental   v1.6.1
httproutes.gateway.networking.k8s.io                  experimental   v1.6.1
listenersets.gateway.networking.k8s.io                experimental   v1.6.1
referencegrants.gateway.networking.k8s.io             experimental   v1.6.1
tcproutes.gateway.networking.k8s.io                   experimental   v1.6.1
tlsroutes.gateway.networking.k8s.io                   experimental   v1.6.1
udproutes.gateway.networking.k8s.io                   experimental   v1.6.1
xbackends.gateway.networking.x-k8s.io                 experimental   v1.6.1
xbackendtrafficpolicies.gateway.networking.x-k8s.io   experimental   v1.6.1
xmeshes.gateway.networking.x-k8s.io                   experimental   v1.6.1

Das Envoy-Gateway-Chart bringt den Experimental-Channel von Gateway API v1.6.1 mit. Er ist eine Obermenge des Standard-Channels: dieselben v1-Ressourcen plus experimentelle Felder (z. B. retry in HTTPRoute, Tag 3) und x-k8s.io-Ressourcen.

Channel Inhalt Einsatz
Standard GA-Ressourcen und -Felder, stabil Produktion
Experimental Standard plus Alpha-Felder und x-k8s.io-Typen Lab, gezielte Features

Im Buch nutzen wir nur Standard-Felder – außer wo ein Kapitel ausdrücklich „experimentell” sagt.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die API selbst befragen

kubectl explain gateway.spec.listeners | sed -n '/^FIELDS/,$p' | grep -E '^  [a-zA-Z]'
kubectl explain httproute.spec.rules | sed -n '/^FIELDS/,$p' | grep -E '^  [a-zA-Z]'

Erwartet:

  allowedRoutes <Object>
  hostname  <string>
  name  <string> -required-
  port  <integer> -required-
  protocol  <string> -required-
  tls   <Object>
  backendRefs   <[]Object>
  filters   <[]Object>
  matches   <[]Object>
  name  <string>
  retry <Object>
  sessionPersistence    <Object>
  timeouts  <Object>
kubectl explain httproute.spec.rules.filters.type | sed -n '/ENUM/,/^$/p'

Erwartet:

ENUM:
    RequestHeaderModifier
    ResponseHeaderModifier
    RequestMirror
    RequestRedirect
    URLRewrite
    ExtensionRef
    CORS
    ExternalAuth

Das ist die Liste, die bei Ingress in Annotationen verstreut war. ExtensionRef ist die Tür für herstellerspezifische Filter (Envoy Gateway: HTTPRouteFilter, Tag 10). retry, sessionPersistence und ExternalAuth siehst du nur, weil der Experimental-Channel installiert ist.

Fortschritt speichern? Kostenlos registrieren

Drill 6: GatewayClass anlegen und Status lesen

cat > ~/gw-lab/code/demo/gatewayclass.yaml <<'EOF'
# GatewayClass für Envoy Gateway (Tag 1)
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
EOF
kubectl apply -f ~/gw-lab/code/demo/gatewayclass.yaml
kubectl get gatewayclass

Erwartet:

gatewayclass.gateway.networking.k8s.io/eg created
NAME   CONTROLLER                                      ACCEPTED   AGE
eg     gateway.envoyproxy.io/gatewayclass-controller   True       3s
kubectl get gatewayclass eg -o yaml | sed -n '/^status/,$p'

Erwartet:

status:
  conditions:
  - lastTransitionTime: "2026-10-09T21:09:26Z"
    message: Valid GatewayClass
    observedGeneration: 1
    reason: Accepted
    status: "True"
    type: Accepted

So liest du jede Condition: type (was wird geprüft), status (True/False/Unknown), reason (maschinenlesbar), message (für Menschen) und observedGeneration (bezieht sich der Status auf die aktuelle Spec?).

Kurzform für alle folgenden Tage – ein kleines Hilfsskript:

cat > ~/gw-lab/code/demo/conds.sh <<'EOF'
#!/usr/bin/env bash
# Zeigt die Conditions einer Gateway-API-Ressource kompakt an.
# Aufruf: conds.sh <kind> <name> [namespace]
#   GatewayClass: eigene Conditions · Gateway: zusätzlich pro Listener
#   Routes/Policies: Conditions pro Parent (status.parents / status.ancestors)
set -euo pipefail
kind="$1"; name="$2"; ns="${3:-default}"
nl='{"\n"}'
c="{range .conditions[*]}  {.type}={.status} ({.reason}): {.message}$nl{end}"
top="{range .status.conditions[*]}{.type}={.status} ({.reason}): {.message}$nl{end}"
case "$kind" in
  gatewayclass|gc)
    kubectl get gatewayclass "$name" -o jsonpath="$top" ;;
  gateway|gtw)
    lst="{range .status.listeners[*]}listener {.name}"
    lst+=" (attachedRoutes={.attachedRoutes}):$nl$c{end}"
    kubectl -n "$ns" get gateway "$name" -o jsonpath="$top$lst" ;;
  *)
    par="{range .status.parents[*]}parent {.parentRef.namespace}/"
    par+="{.parentRef.name}/{.parentRef.sectionName}:$nl$c{end}"
    anc="{range .status.ancestors[*]}ancestor {.ancestorRef.namespace}/"
    anc+="{.ancestorRef.name}/{.ancestorRef.sectionName}:$nl$c{end}"
    kubectl -n "$ns" get "$kind" "$name" -o jsonpath="$par$anc" ;;
esac
EOF
chmod +x ~/gw-lab/code/demo/conds.sh
export PATH="$HOME/gw-lab/code/demo:$PATH"
conds.sh gatewayclass eg

Erwartet:

Accepted=True (Accepted): Valid GatewayClass

Lege den PATH-Eintrag auch in ~/.zshrc bzw. ~/.bashrc ab. Ab jetzt rufst du conds.sh und gw-ip.sh ohne Pfad auf.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Kein Status ist auch eine Antwort

cat <<'EOF' | kubectl apply -f -
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: falsch
spec:
  controllerName: example.com/gibt-es-nicht
EOF
kubectl get gatewayclass
kubectl get gatewayclass falsch -o jsonpath='{.status.conditions[*].reason}'; echo

Erwartet:

gatewayclass.gateway.networking.k8s.io/falsch created
NAME     CONTROLLER                                      ACCEPTED   AGE
eg       gateway.envoyproxy.io/gatewayclass-controller   True       10m
falsch   example.com/gibt-es-nicht                       Unknown    3s
Pending

Unknown/Pending ist der Default, den der API-Server beim Anlegen einträgt. Kein Controller hat sich die Klasse geholt – Envoy Gateway ignoriert alles, was nicht seinen controllerName trägt. Das ist die häufigste Fehlerquelle beim Wechsel der Implementierung: falscher Klassenname am Gateway, und nichts passiert.

kubectl delete gatewayclass falsch
kubectl -n shop delete ingress shop

Erwartet:

gatewayclass.gateway.networking.k8s.io "falsch" deleted
ingress.networking.k8s.io "shop" deleted from shop namespace

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Envoy Gateway verfügbar" \
  'kubectl -n envoy-gateway-system wait deploy/envoy-gateway \
     --for=condition=Available --timeout=5s'
check "HTTPRoute-CRD aus Bundle v1.6.x" \
  'kubectl get crd httproutes.gateway.networking.k8s.io \
     -o jsonpath="{.metadata.annotations}" | grep -q "bundle-version\":\"v1.6"'
check "GatewayClass eg akzeptiert" \
  'kubectl wait gatewayclass/eg --for=condition=Accepted --timeout=5s'
check "GatewayClass falsch entfernt" '! kubectl get gatewayclass falsch'
check "conds.sh im PATH" 'command -v conds.sh'

Erwartet:

✔ Envoy Gateway verfügbar
✔ HTTPRoute-CRD aus Bundle v1.6.x
✔ GatewayClass eg akzeptiert
✔ GatewayClass falsch entfernt
✔ conds.sh im PATH

Challenge

Alle Gateway-API-Ressourcen werden als v1 ausgeliefert. Finde die eine CRD, die ihre Objekte in etcd trotzdem noch in einer anderen Version speichert.

Hinweis: Jede Version in spec.versions hat ein Feld storage: true|false.

Lösung

kubectl get crd -o json | jq -r '.items[]
  | select(.spec.group == "gateway.networking.k8s.io")
  | "\(.metadata.name) storage=\(.spec.versions[] | select(.storage) | .name)"'

Erwartet:

backendtlspolicies.gateway.networking.k8s.io storage=v1
gatewayclasses.gateway.networking.k8s.io storage=v1
gateways.gateway.networking.k8s.io storage=v1
grpcroutes.gateway.networking.k8s.io storage=v1
httproutes.gateway.networking.k8s.io storage=v1
listenersets.gateway.networking.k8s.io storage=v1
referencegrants.gateway.networking.k8s.io storage=v1beta1
tcproutes.gateway.networking.k8s.io storage=v1
tlsroutes.gateway.networking.k8s.io storage=v1
udproutes.gateway.networking.k8s.io storage=v1

ReferenceGrant ist seit v1.5 als v1 verfügbar, gespeichert wird aber noch v1beta1. Für dich als Nutzer egal – beim CRD-Upgrade (Tag 12) aber genau die Stelle, an der eine Storage-Migration fällig werden kann.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In Produktion gehören die Gateway-API-CRDs dem Plattform-Team und werden getrennt vom Controller verwaltet (Envoy Gateway: Chart gateway-crds-helm, im Haupt-Chart crds.enabled=false). Mehrere Implementierungen teilen sich dieselben CRDs.
  • Standard-Channel bevorzugen. Seit v1.5 verhindert die ValidatingAdmissionPolicy safe-upgrades.gateway.networking.k8s.io den Wechsel von Standard auf Experimental und Downgrades unter v1.5.
  • Version immer gegen die Kompatibilitätsmatrix des Controllers prüfen: Envoy Gateway v1.9 ist für Gateway API v1.6.1 gebaut.
  • RBAC nach Rollen schneiden: GatewayClass nur für Cluster-Admins, Gateways nur fürs Plattform-Team, Routes für App-Teams in ihren Namespaces (Tag 7).