Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: Erstes Gateway und HTTPRoute

Ziel: Ein Gateway im Namespace infra nimmt Traffic an, HTTPRoutes aus shop verteilen 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 parentRefs an ein Gateway, optional per sectionName an 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: Gateway Programmed, Route Accepted und ResolvedRefs.
 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 -w

Erwartet (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 infra

Erwartet (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=web

Erwartet (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 -1

Erwartet:

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 shop

Erwartet:

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 attachedRoutes

Erwartet:

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
done

Erwartet:

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 mit no matches found ab.

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/x

Erwartet:

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; done

Erwartet (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 -1

Erwartet:

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.yaml

Damit 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-debug

Erwartet:

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: All ist nur fürs Lab. Beim Kunden: Selector auf ein Namespace-Label oder Same (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 apply ist erst dann erfolgreich, wenn Accepted und ResolvedRefs auf True stehen (Tag 11).
  • Regex-Pfade (RegularExpression) sind implementierungsspezifisch – vermeide sie, wenn du die Implementierung wechseln können willst.