Tag 2: Erstes Gateway und HTTPRoute
Ziel: Ein Gateway im Namespace
infranimmt Traffic an, HTTPRoutes ausshopverteilen ihn nach Pfad, Header und Query. · Dauer: ca. 60 min · Voraussetzung: Tag 1
Briefing
- Ein Gateway ist eine Liste von Listenern (Port, Protokoll, optional Hostname und TLS). Envoy Gateway baut pro Gateway ein Envoy-Deployment plus LoadBalancer-Service.
- Eine HTTPRoute hängt sich per
parentRefsan ein Gateway, optional persectionNamean genau einen Listener. - Route-Hostnames und Listener-Hostname müssen sich überschneiden, sonst wird die Route nicht akzeptiert.
- Innerhalb einer Regel gilt: Bedingungen in einem Match-Eintrag sind UND, mehrere Match-Einträge sind ODER.
- Debuggen beginnt immer bei
status: GatewayProgrammed, RouteAcceptedundResolvedRefs.
curl --resolve shop...:80:$GW_IP
│
▼
kindccm-… (LB-IP) ─► Service envoy-infra-web-… ─► Envoy-Pod (ns envoy-gateway-system)
│ Config per xDS vom Controller
Gateway infra/web ◄── parentRefs ── HTTPRoute shop/shop
│
▼
Service shop-v1 / shop-v2
Drill 1: Das Gateway anlegen
cat > ~/gw-lab/code/demo/gateway.yaml <<'EOF'
# Gateway des Plattform-Teams (Stand nach Tag 2)
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
namespace: infra
spec:
gatewayClassName: eg
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All # an Tag 7 eingeschränkt
EOF
kubectl apply -f ~/gw-lab/code/demo/gateway.yaml
kubectl -n infra get gateway web -wErwartet (nach 20–60 s, IP kann abweichen; Ctrl+C
beendet -w):
gateway.gateway.networking.k8s.io/web created
NAME CLASS ADDRESS PROGRAMMED AGE
web eg False 0s
web eg 172.18.0.8 True 41s
conds.sh gateway web infraErwartet (Meldungen gekürzt):
Accepted=True (Accepted): The Gateway has been scheduled by Envoy Gateway
Programmed=True (Programmed): Address assigned to the Gateway, 1/1 envoy replicas …
listener http (attachedRoutes=0):
Programmed=True (Programmed): Sending translated listener configuration to the …
Accepted=True (Accepted): Listener has been successfully translated
ResolvedRefs=True (ResolvedRefs): Listener references have been resolved
Accepted heißt: Die Spec ist gültig.
Programmed heißt: Die Datenebene ist bereit und hat eine
Adresse. attachedRoutes=0 – noch hängt keine Route am
Listener.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Was Envoy Gateway daraus baut
kubectl -n envoy-gateway-system get deploy,svc \
-l gateway.envoyproxy.io/owning-gateway-name=webErwartet (gekürzt, Hash-Suffix weicht ab):
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/envoy-infra-web-a97fc3bf 1/1 1 1 41s
NAME TYPE EXTERNAL-IP PORT(S)
service/envoy-infra-web-a97fc3bf LoadBalancer 172.18.0.8 80:32072/TCP
Das Gateway lebt in infra, die Proxys aber im Namespace
des Controllers. Der Name folgt dem Schema
envoy-<namespace>-<gateway>-<hash>. Die
externe IP des Service ist die Adresse im Gateway-Status.
export GW_IP=$(gw-ip.sh)
echo "$GW_IP"
curl -si --resolve shop.gw.localtest.me:80:$GW_IP http://shop.gw.localtest.me/ | head -1Erwartet:
172.18.0.8
HTTP/1.1 404 Not Found
Envoy antwortet bereits – nur kennt er noch keine Route. Ein 404 vom Gateway ist also ein gutes Zeichen: Netzwerk und Listener funktionieren.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Die erste HTTPRoute
cat > ~/gw-lab/code/demo/route-shop.yaml <<'EOF'
# Basis-Route des Shop-Teams (Stand nach Tag 2)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: http
hostnames:
- shop.gw.localtest.me
rules:
- backendRefs:
- name: shop-v1
port: 80
EOF
kubectl apply -f ~/gw-lab/code/demo/route-shop.yaml
kubectl -n shop get httproute
conds.sh httproute shop shopErwartet:
httproute.gateway.networking.k8s.io/shop created
NAME HOSTNAMES AGE
shop ["shop.gw.localtest.me"] 3s
parent infra/web/http:
Accepted=True (Accepted): Route is accepted
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
http://shop.gw.localtest.me/hallo | jq -c '{path, host, service, pod}'
curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
http://shop.gw.localtest.me/hallo | jq -c '.headers | keys'Erwartet:
{"path":"/hallo","host":"shop.gw.localtest.me","service":"shop-v1","pod":"shop-v1-…"}
["Accept","User-Agent","X-Envoy-External-Address","X-Forwarded-For",
"X-Forwarded-Proto","X-Request-Id"]
Der Status steht bei Routes pro Parent in
status.parents[] – eine Route kann an mehreren Gateways
hängen und dort unterschiedlich gut ankommen. Envoy ergänzt
X-Forwarded-* und eine X-Request-Id für die
Nachverfolgung (Tag 11).
conds.sh gateway web infra | grep attachedRoutesErwartet:
listener http (attachedRoutes=1):
Fortschritt speichern? Kostenlos registrieren
Drill 4: Pfade matchen
cd ~/gw-lab/tag02
cat > shop-matching.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: http
hostnames:
- shop.gw.localtest.me
rules:
- name: v2-pfad
matches:
- path:
type: PathPrefix
value: /v2
backendRefs:
- name: shop-v2
port: 80
- name: v2-optin
matches:
- headers:
- name: x-version
value: v2
- queryParams:
- name: version
value: v2
backendRefs:
- name: shop-v2
port: 80
- name: beta
matches:
- path:
type: PathPrefix
value: /beta
headers:
- name: x-beta
value: "1"
backendRefs:
- name: shop-v2
port: 80
- name: rest
backendRefs:
- name: shop-v1
port: 80
EOF
kubectl apply -f shop-matching.yaml
for p in / /v2 /v2/warenkorb /v2x; do
printf '%-15s -> ' "$p"
curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
"http://shop.gw.localtest.me$p" | jq -r .service
doneErwartet:
httproute.gateway.networking.k8s.io/shop configured
/ -> shop-v1
/v2 -> shop-v2
/v2/warenkorb -> shop-v2
/v2x -> shop-v1
PathPrefix vergleicht ganze Pfadsegmente:
/v2 passt auf /v2 und /v2/…, aber
nicht auf /v2x. Bei ingress-nginx hängt dieses Verhalten
von pathType und Regex-Annotationen ab – hier ist es
spezifiziert. Eine Regel ohne matches (hier
rest) bekommt implizit PathPrefix /.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Header, Query und die UND/ODER-Logik
s() { curl -s --resolve shop.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
s -H 'x-version: v2' http://shop.gw.localtest.me/
s -H 'X-Version: v2' http://shop.gw.localtest.me/
s -H 'x-version: V2' http://shop.gw.localtest.me/
s 'http://shop.gw.localtest.me/?version=v2'Erwartet:
shop-v2
shop-v2
shop-v1
shop-v2
Header-Namen sind case-insensitiv,
Werte nicht: V2 ist nicht v2.
Die Regel v2-optin hat zwei Match-Einträge – Header
oder Query reicht.
s http://shop.gw.localtest.me/beta
s -H 'x-beta: 1' http://shop.gw.localtest.me/beta/neu
s -H 'x-beta: 1' http://shop.gw.localtest.me/Erwartet:
shop-v1
shop-v2
shop-v1
Regel beta hat einen Match-Eintrag mit
Pfad und Header: beide müssen passen.
Tipp: Setze URLs mit
?immer in Anführungszeichen. zsh versucht sonst, sie als Glob-Muster aufzulösen, und bricht mitno matches foundab.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Zweiter Listener mit Hostname
Das Plattform-Team gibt dem API-Team einen eigenen Listener, der nur
api.gw.localtest.me annimmt.
cat > gateway-api-listener.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
namespace: infra
spec:
gatewayClassName: eg
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
- name: http-api
protocol: HTTP
port: 80
hostname: api.gw.localtest.me
allowedRoutes:
namespaces:
from: All
EOF
cat > api.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: http-api
rules:
- matches:
- path:
type: Exact
value: /info
method: GET
backendRefs:
- name: shop-v2
port: 80
- backendRefs:
- name: shop-v1
port: 80
EOF
kubectl apply -f gateway-api-listener.yaml -f api.yaml
a() { curl -s --resolve api.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
a http://api.gw.localtest.me/info
a -X POST http://api.gw.localtest.me/info
a http://api.gw.localtest.me/info/xErwartet:
gateway.gateway.networking.k8s.io/web configured
httproute.gateway.networking.k8s.io/api created
shop-v2
shop-v1
shop-v1
Die Route api hat keine eigenen hostnames –
sie erbt den Hostname des Listeners. Exact passt nur exakt
auf /info, method: GET schließt POST aus.
Beide Listener teilen sich Port 80; Envoy unterscheidet sie am
Host-Header.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Status debuggen – drei typische Fehler
cat > kaputt.yaml <<'EOF'
# Fehler 1: Route-Hostname passt nicht zum Listener http-api
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: kaputt
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: http-api
hostnames:
- shop.gw.localtest.me
rules:
- backendRefs:
- name: shop-v1
port: 80
---
# Fehler 2: Service existiert nicht
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: kaputt2
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
hostnames:
- kaputt.gw.localtest.me
rules:
- backendRefs:
- name: shop-v3
port: 80
---
# Fehler 3: parentRef ohne Namespace -> sucht Gateway "web" in "shop"
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: kaputt3
namespace: shop
spec:
parentRefs:
- name: web
hostnames:
- kaputt.gw.localtest.me
rules:
- backendRefs:
- name: shop-v1
port: 80
EOF
kubectl apply -f kaputt.yaml
for r in kaputt kaputt2 kaputt3; do echo "== $r"; conds.sh httproute $r shop; doneErwartet (Meldungen gekürzt):
== kaputt
parent infra/web/http-api:
Accepted=False (NoMatchingListenerHostname): There were no hostname intersections …
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
== kaputt2
parent infra/web/:
Accepted=True (Accepted): Route is accepted
ResolvedRefs=False (BackendNotFound): Failed to process route rule 0 backendRef 0: …
== kaputt3
curl -si --resolve kaputt.gw.localtest.me:80:$GW_IP \
http://kaputt.gw.localtest.me/ | head -1Erwartet:
HTTP/1.1 500 Internal Server Error
| Symptom | Ursache | Wo du es siehst |
|---|---|---|
Accepted=False,
NoMatchingListenerHostname |
Hostnames überschneiden sich nicht | Route-Status |
ResolvedRefs=False, BackendNotFound, HTTP
500 |
Service/Port falsch | Route-Status |
| gar kein Status | Gateway gibt es so nicht, kein Controller fühlt sich zuständig | fehlendes status |
attachedRoutes bleibt 0 |
Route hängt nicht am Listener | Gateway-Status |
kaputt2 ist akzeptiert, aber kaputt: Die Regel
existiert, ihr Backend nicht. Envoy antwortet deshalb mit 500 statt 404
– ein wichtiger Unterschied beim Fehlersuchen.
kubectl -n shop delete httproute kaputt kaputt2 kaputt3 api
kubectl apply -f ~/gw-lab/code/demo/gateway.yaml -f ~/gw-lab/code/demo/route-shop.yamlDamit ist der Stand wieder die Basis aus code/demo, auf
der Tag 3 aufbaut.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
GW_IP=$(gw-ip.sh)
check "Gateway web Programmed" \
'kubectl -n infra wait gateway/web --for=condition=Programmed --timeout=5s'
check "Gateway hat Adresse ($GW_IP)" '[ -n "$GW_IP" ]'
check "Route shop akzeptiert" \
'conds.sh httproute shop shop | grep -q "Accepted=True"'
check "shop.gw.localtest.me -> shop-v1" \
'[ "$(curl -s --resolve shop.gw.localtest.me:80:$GW_IP \
http://shop.gw.localtest.me/ | jq -r .service)" = shop-v1 ]'
check "keine Übungs-Routes mehr" \
'[ "$(kubectl -n shop get httproute --no-headers | wc -l)" -eq 1 ]'Erwartet:
✔ Gateway web Programmed
✔ Gateway hat Adresse (172.18.0.8)
✔ Route shop akzeptiert
✔ shop.gw.localtest.me -> shop-v1
✔ keine Übungs-Routes mehr
Challenge
Ein zweites Team will Debug-Traffic abzweigen, ohne die Route
shop anzufassen: Lege eine eigene HTTPRoute
shop-debug für denselben Hostname an, die Requests mit
Header x-debug: true an shop-v2 schickt.
Normale Requests müssen weiter bei shop-v1 landen.
Hinweis: Alle Routes für denselben Hostname werden zu einer Routing-Tabelle zusammengeführt; der spezifischere Match gewinnt.
Lösung
cat > ~/gw-lab/tag02/shop-debug.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop-debug
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
hostnames:
- shop.gw.localtest.me
rules:
- matches:
- headers:
- name: x-debug
value: "true"
backendRefs:
- name: shop-v2
port: 80
EOF
kubectl apply -f ~/gw-lab/tag02/shop-debug.yaml
s() { curl -s --resolve shop.gw.localtest.me:80:$GW_IP "$@" | jq -r .service; }
s http://shop.gw.localtest.me/
s -H 'x-debug: true' http://shop.gw.localtest.me/egal
conds.sh gateway web infra | grep attachedRoutes
kubectl -n shop delete httproute shop-debugErwartet:
httproute.gateway.networking.k8s.io/shop-debug created
shop-v1
shop-v2
listener http (attachedRoutes=2):
httproute.gateway.networking.k8s.io "shop-debug" deleted from shop namespace
Bei gleich spezifischen Matches entscheidet laut Spezifikation die
ältere Route (creationTimestamp), danach der Name
alphabetisch.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Ein Gateway pro Vertrauenszone (extern, intern, Partner) statt eines Gateways für alles; jedes bekommt eigene IP, eigene Envoy-Pods und eigene Policies.
allowedRoutes.namespaces.from: Allist nur fürs Lab. Beim Kunden:Selectorauf ein Namespace-Label oderSame(Tag 7).- Hostnames gehören an den Listener, sobald TLS ins Spiel kommt (Tag 4): Der Listener legt fest, für welche Namen das Plattform-Team Zertifikate verantwortet.
- Route-Status in die Deployment-Pipeline aufnehmen: Ein
kubectl applyist erst dann erfolgreich, wennAcceptedundResolvedRefsaufTruestehen (Tag 11). - Regex-Pfade (
RegularExpression) sind implementierungsspezifisch – vermeide sie, wenn du die Implementierung wechseln können willst.