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 aufservice/methodund Header statt auf Pfade. Ingress konnte das nur überbackend-protocol: GRPCplus Pfad-Tricks. - gRPC braucht HTTP/2. Zum Backend sagt
appProtocol: kubernetes.io/h2cam Service: Klartext-HTTP/2. - TCPRoute und UDPRoute sind seit
Gateway API v1.6
v1im 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-grpcErwartet:
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=90sErwartet (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 paymentsErwartet:
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.GrpcEchoErwartet:
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]+'
doneErwartet:
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/EchoThreeErwartet:
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, dannmethod, 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=60sErwartet (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" 9100Erwartet:
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 -1Erwartet:
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 -cErwartet (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
BackendTrafficPolicyanpassen (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.