Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: gRPC, TCP und UDP

Ziel: Du routest gRPC nach Service und Methode, testest mit grpcurl und hängst reine TCP- und UDP-Dienste an dasselbe Gateway. · Dauer: ca. 60 min · Voraussetzung: Tag 4

Briefing

  • GRPCRoute (v1, Standard seit Gateway API v1.1) matcht auf service/method und Header statt auf Pfade. Ingress konnte das nur über backend-protocol: GRPC plus Pfad-Tricks.
  • gRPC braucht HTTP/2. Zum Backend sagt appProtocol: kubernetes.io/h2c am Service: Klartext-HTTP/2.
  • TCPRoute und UDPRoute sind seit Gateway API v1.6 v1 im Standard-Channel. Sie haben keine Matches – ein Listener-Port gehört genau einem Dienst.
  • Envoy Gateway legt pro Listener-Port einen Port am LoadBalancer-Service an. cloud-provider-kind veröffentlicht ihn auf $GW_IP.
grpcurl ─TLS:443 SNI grpc─> Listener https-grpc ─h2c─> payments    (Echo)
                                                └─h2c─> payments-v2 (EchoTwo, x-version)
nc      ─TCP:9100────────> Listener tcp  ─> tcp-echo:9100
nc -u   ─UDP:9200────────> Listener udp  ─> udp-echo:9200

Drill 1: gRPC-Listener mit Zertifikat

grpcurl kommt aus Tag 0. Das Plattform-Team ergänzt einen HTTPS-Listener nur für GRPCRoutes; der gateway-shim aus Tag 4 stellt das Zertifikat aus.

mkdir -p ~/gw-lab/tag06 && cd ~/gw-lab/tag06
export GW_IP=$(gw-ip.sh) CA=~/gw-lab/tag04/lab-ca.crt
kubectl -n infra patch gateway web --type=json -p '[{"op":"add",
  "path":"/spec/listeners/-","value":{"name":"https-grpc","protocol":"HTTPS",
  "port":443,"hostname":"grpc.gw.localtest.me",
  "tls":{"mode":"Terminate","certificateRefs":[{"name":"grpc-gw-tls"}]},
  "allowedRoutes":{"namespaces":{"from":"All"},"kinds":[{"kind":"GRPCRoute"}]}}}]'
sleep 15
kubectl -n infra get certificate grpc-gw-tls
conds.sh gateway web infra | grep -A3 https-grpc

Erwartet:

gateway.gateway.networking.k8s.io/web patched
NAME          READY   SECRET        AGE
grpc-gw-tls   True    grpc-gw-tls   15s
listener https-grpc (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

kinds: [GRPCRoute] sorgt dafür, dass niemand versehentlich eine HTTPRoute an den gRPC-Hostname hängt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Zweite Version und GRPCRoute

Für sichtbares Methoden-Routing brauchst du ein zweites Backend:

cat > payments-v2.yaml <<'EOF'
# Zweite Version des gRPC-Dienstes, um Methoden-Routing sichtbar zu machen
apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-v2
  namespace: payments
  labels: {app: payments-v2}
spec:
  replicas: 1
  selector:
    matchLabels: {app: payments-v2}
  template:
    metadata:
      labels: {app: payments-v2}
    spec:
      containers:
        - name: grpc-echo
          image: registry.k8s.io/gateway-api/echo-basic:v1.6.0
          env:
            - {name: GRPC_ECHO_SERVER, value: "1"}
            - {name: SERVICE_NAME, value: payments-v2}
            - name: POD_NAME
              valueFrom: {fieldRef: {fieldPath: metadata.name}}
            - name: NAMESPACE
              valueFrom: {fieldRef: {fieldPath: metadata.namespace}}
          ports:
            - {name: grpc, containerPort: 3000}
          readinessProbe:
            tcpSocket: {port: grpc}
          resources:
            requests: {cpu: 10m, memory: 16Mi}
            limits: {memory: 64Mi}
---
apiVersion: v1
kind: Service
metadata:
  name: payments-v2
  namespace: payments
spec:
  selector: {app: payments-v2}
  ports:
    - name: grpc
      port: 3000
      targetPort: grpc
      appProtocol: kubernetes.io/h2c
EOF
kubectl apply -f payments-v2.yaml
kubectl -n payments rollout status deploy/payments-v2 --timeout=90s

Erwartet (gekürzt):

deployment.apps/payments-v2 created
service/payments-v2 created
deployment "payments-v2" successfully rolled out

Jetzt die Route. Regel 1 lässt Server Reflection durch, damit grpcurl ohne .proto-Datei arbeiten kann:

cat > grpcroute.yaml <<'EOF'
# gRPC-Routing nach Service/Methode und Header
apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
  name: payments
  namespace: payments
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: https-grpc
  hostnames:
    - grpc.gw.localtest.me
  rules:
    # Reflection, damit grpcurl list/describe funktionieren
    - matches:
        - method:
            service: grpc.reflection.v1.ServerReflection
        - method:
            service: grpc.reflection.v1alpha.ServerReflection
      backendRefs:
        - {name: payments, port: 3000}
    # Echo -> v1; EchoTwo -> v2; Tester mit x-version: v2 immer -> v2
    - matches:
        - method:
            service: gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
            method: Echo
      backendRefs:
        - {name: payments, port: 3000}
    - matches:
        - method:
            service: gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
            method: EchoTwo
        - headers:
            - {name: x-version, value: v2}
      backendRefs:
        - {name: payments-v2, port: 3000}
EOF
kubectl apply -f grpcroute.yaml
conds.sh grpcroute payments payments

Erwartet:

grpcroute.gateway.networking.k8s.io/payments created
parent infra/web/https-grpc:
  Accepted=True (Accepted): Route is accepted
  ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route

Mehrere Einträge unter matches sind ODER, Felder innerhalb eines Eintrags UND – wie bei der HTTPRoute (Tag 2).

Fortschritt speichern? Kostenlos registrieren

Drill 3: grpcurl durch das Gateway

g() { grpcurl -cacert "$CA" -authority grpc.gw.localtest.me "$@"; }
g "$GW_IP:443" list
g "$GW_IP:443" describe gateway_api_conformance.echo_basic.grpcecho.GrpcEcho

Erwartet:

gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
grpc.reflection.v1.ServerReflection
grpc.reflection.v1alpha.ServerReflection
gateway_api_conformance.echo_basic.grpcecho.GrpcEcho is a service:
service GrpcEcho {
  rpc Echo ( .gateway_api_conformance.echo_basic.grpcecho.EchoRequest ) returns ...
  rpc EchoThree ( .gateway_api_conformance.echo_basic.grpcecho.EchoRequest ) ...
  rpc EchoTwo ( .gateway_api_conformance.echo_basic.grpcecho.EchoRequest ) ...
}

-authority setzt :authority und den TLS-Servernamen (SNI) – das Pendant zu --resolve bei curl. Ein Aufruf zeigt, was beim Backend ankommt:

S=gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
g "$GW_IP:443" $S/Echo | jq -c '.assertions | {authority, context}'

Erwartet:

{"authority":"grpc.gw.localtest.me","context":{"namespace":"payments",
"serviceName":"payments","pod":"payments-6cfbdd9c64-hrk6z"}}

(Ausgabe zur Lesbarkeit umbrochen.)

Fortschritt speichern? Kostenlos registrieren

Drill 4: Methoden-Routing und Vorrang

for m in Echo EchoTwo EchoThree; do
  printf '%-10s ' $m
  g "$GW_IP:443" $S/$m 2>&1 | grep -oE '"serviceName": "[^"]+"|Code: [A-Za-z]+'
done

Erwartet:

Echo       "serviceName": "payments"
EchoTwo    "serviceName": "payments-v2"
EchoThree  Code: Unimplemented

EchoThree passt auf keine Regel. Envoy antwortet selbst mit gRPC-Status 12 Unimplemented – das gRPC-Gegenstück zu HTTP 404. Jetzt mit Tester-Header:

g -H 'x-version: v2' "$GW_IP:443" $S/Echo | jq -r .assertions.context.serviceName
g -H 'x-version: v2' "$GW_IP:443" $S/EchoThree

Erwartet:

payments
ERROR:
  Code: Unimplemented
  Message: method EchoThree not implemented

Zwei Lektionen: Echo mit Header bleibt bei payments, weil ein Methoden-Match Vorrang vor einem reinen Header-Match hat. EchoThree mit Header erreicht jetzt payments-v2 – die Fehlermeldung kommt diesmal vom Backend, nicht von Envoy.

Tipp: Vorrang bei GRPCRoute: exakter Hostname vor Wildcard, dann Länge von service, dann method, dann Anzahl der Header-Matches.

Fortschritt speichern? Kostenlos registrieren

Drill 5: TCPRoute

Ein TCP-Echo (gleiches Image, anderer Modus) und ein UDP-Echo für Drill 6:

cat > l4-echo.yaml <<'EOF'
# TCP- und UDP-Echo: gleiches Image echo-basic, anderer Modus
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tcp-echo
  namespace: payments
spec:
  replicas: 1
  selector:
    matchLabels: {app: tcp-echo}
  template:
    metadata:
      labels: {app: tcp-echo}
    spec:
      containers:
        - name: echo
          image: registry.k8s.io/gateway-api/echo-basic:v1.6.0
          env:
            - {name: TCP_ECHO_SERVER, value: "1"}
            - {name: TCP_PORT, value: "9100"}
            - {name: SERVICE_NAME, value: tcp-echo}
            - name: POD_NAME
              valueFrom: {fieldRef: {fieldPath: metadata.name}}
          resources:
            requests: {cpu: 10m, memory: 16Mi}
---
apiVersion: v1
kind: Service
metadata:
  name: tcp-echo
  namespace: payments
spec:
  selector: {app: tcp-echo}
  ports:
    - {name: tcp, port: 9100, targetPort: 9100, protocol: TCP}
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: udp-echo
  namespace: payments
spec:
  replicas: 1
  selector:
    matchLabels: {app: udp-echo}
  template:
    metadata:
      labels: {app: udp-echo}
    spec:
      containers:
        - name: echo
          image: registry.k8s.io/gateway-api/echo-basic:v1.6.0
          env:
            - {name: UDP_ECHO_SERVER, value: "1"}
            - {name: UDP_PORT, value: "9200"}
            - {name: SERVICE_NAME, value: udp-echo}
            - name: POD_NAME
              valueFrom: {fieldRef: {fieldPath: metadata.name}}
          resources:
            requests: {cpu: 10m, memory: 16Mi}
---
apiVersion: v1
kind: Service
metadata:
  name: udp-echo
  namespace: payments
spec:
  selector: {app: udp-echo}
  ports:
    - {name: udp, port: 9200, targetPort: 9200, protocol: UDP}
EOF
kubectl apply -f l4-echo.yaml
kubectl -n payments rollout status deploy/tcp-echo --timeout=60s
kubectl -n payments rollout status deploy/udp-echo --timeout=60s

Erwartet (gekürzt):

deployment "tcp-echo" successfully rolled out
deployment "udp-echo" successfully rolled out

Listener für TCP-Port 9100, Route dazu:

kubectl -n infra patch gateway web --type=json -p '[{"op":"add",
  "path":"/spec/listeners/-","value":{"name":"tcp","protocol":"TCP","port":9100,
  "allowedRoutes":{"namespaces":{"from":"All"},"kinds":[{"kind":"TCPRoute"}]}}}]'
cat > tcproute.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: TCPRoute
metadata:
  name: tcp-echo
  namespace: payments
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: tcp
  rules:
    - backendRefs:
        - {name: tcp-echo, port: 9100}
EOF
kubectl apply -f tcproute.yaml
sleep 5
conds.sh tcproute tcp-echo payments
printf 'TEST\nIS_TLS\n' | nc -w1 "$GW_IP" 9100

Erwartet:

gateway.gateway.networking.k8s.io/web patched
tcproute.gateway.networking.k8s.io/tcp-echo created
parent infra/web/tcp:
  Accepted=True (Accepted): Route is accepted
  ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
Gateway API Test TCP Server
{"namespace":"","ingress":"","service":"tcp-echo","pod":"tcp-echo-6dd48d5d-b4ldh",
"tcpport":"9100","tlsport":"8443","isTLS":false}
false

(JSON-Zeile umbrochen.) Kein Hostname, kein Pfad, kein Header: Bei TCP entscheidet nur der Port. Zwei TCPRoutes am selben Listener wären ein Konflikt.

Fortschritt speichern? Kostenlos registrieren

Drill 6: UDPRoute

kubectl -n infra patch gateway web --type=json -p '[{"op":"add",
  "path":"/spec/listeners/-","value":{"name":"udp","protocol":"UDP","port":9200,
  "allowedRoutes":{"namespaces":{"from":"All"},"kinds":[{"kind":"UDPRoute"}]}}}]'
cat > udproute.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: UDPRoute
metadata:
  name: udp-echo
  namespace: payments
spec:
  parentRefs:
    - name: web
      namespace: infra
      sectionName: udp
  rules:
    - backendRefs:
        - {name: udp-echo, port: 9200}
EOF
kubectl apply -f udproute.yaml
sleep 5
echo -n hallo-udp | nc -u -w2 "$GW_IP" 9200; echo
kubectl -n payments logs deploy/udp-echo | tail -1

Erwartet:

gateway.gateway.networking.k8s.io/web patched
udproute.gateway.networking.k8s.io/udp-echo created
{"request":"hallo-udp","namespace":"","ingress":"","service":"udp-echo",
"pod":"udp-echo-6cdb5cc897-6tv8q"}
Received UDP hallo-udp from 10.244.0.10:47085

Die Absenderadresse im Log ist der Envoy-Pod, nicht dein Laptop: Envoy ist für UDP ein nicht-transparenter Proxy.

Tipp: Kommt per UDP nichts zurück? Teste aus dem Cluster, um cloud-provider-kind auszuschließen: kubectl run nc --rm -i --restart=Never --image=busybox:1.37 -- sh -c "echo -n x | nc -u -w2 $GW_IP 9200".

Fortschritt speichern? Kostenlos registrieren

Drill 7: Was Envoy Gateway daraus baut

kubectl -n envoy-gateway-system get svc \
  -l gateway.envoyproxy.io/owning-gateway-name=web \
  -o jsonpath='{range .items[0].spec.ports[*]}{.port}/{.protocol} {end}{"\n"}'
kubectl -n infra get gateway web -o json \
  | jq -r '.status.listeners[] | "\(.name) \(.attachedRoutes)"'

Erwartet:

80/TCP 443/TCP 8443/TCP 9100/TCP 9200/UDP
http 1
https-shop 1
https-api 2
tls-secure 1
https-grpc 1
tcp 1
udp 1

Drei HTTPS-Listener teilen sich Port 443 (SNI), jeder L4-Listener bekommt einen eigenen Port. Auf RKE2 mit Cilium LB-IPAM (Tag 9) gilt dasselbe – prüfe dort, ob deine LB-Implementierung gemischte TCP/UDP-Services kann.

Ressource API (v1.6) Channel Matching
GRPCRoute v1 Standard Hostname, Service/Methode, Header
TLSRoute v1 Standard SNI
TCPRoute v1 Standard nur Listener-Port
UDPRoute v1 Standard nur Listener-Port

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/gw-lab/tag06
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
export GW_IP=$(gw-ip.sh) CA=~/gw-lab/tag04/lab-ca.crt
g() { grpcurl -cacert "$CA" -authority grpc.gw.localtest.me "$@"; }
S=gateway_api_conformance.echo_basic.grpcecho.GrpcEcho
check "GRPCRoute Accepted" \
  'conds.sh grpcroute payments payments | grep -q "Accepted=True"'
check "Echo -> payments" \
  '[ "$(g $GW_IP:443 $S/Echo | jq -r .assertions.context.serviceName)" = payments ]'
check "EchoTwo -> payments-v2" \
  'g $GW_IP:443 $S/EchoTwo | grep -q "\"payments-v2\""'
check "EchoThree ohne Route" '! g $GW_IP:443 $S/EchoThree'
check "TCP-Echo" 'printf "TEST\n" | nc -w1 $GW_IP 9100 | grep -q tcp-echo'
check "UDP-Echo" 'echo -n x | nc -u -w2 $GW_IP 9200 | grep -q udp-echo'

Erwartet:

✔ GRPCRoute Accepted
✔ Echo -> payments
✔ EchoTwo -> payments-v2
✔ EchoThree ohne Route
✔ TCP-Echo
✔ UDP-Echo

Challenge

Rolle Echo als Canary aus: 80 % an payments, 20 % an payments-v2. Miss die Verteilung über 50 Aufrufe.

Hinweis: backendRefs[].weight funktioniert in GRPCRoute genau wie in HTTPRoute.

Lösung

kubectl -n payments patch grpcroute payments --type=json -p '[
  {"op":"replace","path":"/spec/rules/1/backendRefs","value":[
    {"name":"payments","port":3000,"weight":80},
    {"name":"payments-v2","port":3000,"weight":20}]}]'
sleep 3
for _ in $(seq 50); do
  g "$GW_IP:443" $S/Echo | jq -r .assertions.context.serviceName
done | sort | uniq -c

Erwartet (gekürzt, kann je nach Version abweichen; Zahlen schwanken):

grpcroute.gateway.networking.k8s.io/payments patched
  41 payments
   9 payments-v2

Envoy verteilt pro Request, nicht pro Verbindung – auch wenn gRPC eine HTTP/2-Verbindung für viele Aufrufe wiederverwendet.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Lange gRPC-Streams laufen in Envoy-Timeouts (Default 15 s Route-Timeout). Für Streams per BackendTrafficPolicy anpassen (Tag 10).
  • gRPC-Health-Checks und Load-Balancing pro Request statt pro Verbindung sind der Grund, gRPC über ein L7-Gateway statt über einen L4-LoadBalancer zu führen.
  • Reflection nach außen nur in Dev/Test freigeben; in Produktion die Reflection-Regel weglassen oder per SecurityPolicy schützen.
  • TCP/UDP-Listener verbrauchen je einen Port am externen LB: Firewall-Freigaben, Port-Kataloge und Konflikte zwischen Teams zentral verwalten (Tag 7).
  • UDP (DNS, Syslog, QUIC-fremde Protokolle) sieht im Backend nur die Envoy-IP. Braucht der Dienst die Client-IP, ist ein direkter LoadBalancer-Service oft die bessere Wahl.