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 ingressclassErwartet:
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.ioErwartet:
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=AvailableErwartet (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 podsErwartet (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 addgibt es hier nicht; die Version gehört immer mit--versiongepinnt.
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 gatewayclassErwartet:
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 egErwartet:
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}'; echoErwartet:
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 shopErwartet:
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-Chartcrds.enabled=false). Mehrere Implementierungen teilen sich dieselben CRDs. - Standard-Channel bevorzugen. Seit v1.5 verhindert die
ValidatingAdmissionPolicy
safe-upgrades.gateway.networking.k8s.ioden 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).