Tag 10: Envoy-Gateway-Erweiterungen
Ziel: Du steuerst Clients, Backends und Zugriff mit den Policy-CRDs von Envoy Gateway – Rate Limits, Circuit Breaker, Basic Auth, JWT, OIDC mit Keycloak, CORS. · Dauer: ca. 120 min · Voraussetzung: Tag 9
Briefing
- Policies hängen per
targetRefsan Gateway, Listener oder Route (Policy Attachment) und melden ihren Status instatus.ancestors. ClientTrafficPolicy: Client ↔︎ Envoy (Timeouts, HTTP/2, Client-IP). Nur an Gateway/ListenerSet.BackendTrafficPolicy: Envoy ↔︎ Backend (Rate Limit, Retries, Circuit Breaker, Health Checks).SecurityPolicy: wer darf rein (Basic Auth, JWT, OIDC, CORS, IP-Regeln).EnvoyProxy: wie die Envoy-Pods laufen.- Pro Ziel und Policy-Art gilt genau eine Policy; die spezifischere (Route) schlägt die allgemeinere (Gateway).
Client ──[ClientTrafficPolicy]──► Envoy (EnvoyProxy) ──[BackendTrafficPolicy]──► Pod
Gateway web │ SecurityPolicy (Route)
└─► Keycloak (JWKS/Token) · Redis (Rate Limit)
Achtung: Alle Drills laufen auf dem RKE2-Cluster aus Tag 9. Die Manifeste sind mit
kubeconformgegen die CRD-Schemas von Envoy Gateway v1.9.2 und Gateway API v1.6.1 geprüft (strikt, keine unbekannten Felder); CEL-Regeln der CRDs wurden manuell abgeglichen. Ausgaben sind nicht live erzeugt: „(gekürzt, kann je nach Version abweichen)“.
Drill 1: Envoy Gateway erweitern und EnvoyProxy skalieren
Globales Rate Limiting braucht Redis, FQDN-Backends brauchen die
Backend-API. Beides schaltest du im Helm-Release
eg frei:
export KUBECONFIG=~/.kube/rke2-lab.yaml
cd ~/gw-lab/code/tag10
cat eg-values.yamlErwartet:
# Envoy Gateway v1.9.2 – Erweiterungen fuer Tag 10
config:
envoyGateway:
rateLimit:
backend:
type: Redis
redis:
url: redis.redis-system.svc.cluster.local:6379
extensionApis:
enableBackend: true # Backend-CRD (FQDN-Backends, Drill 6)kubectl apply -f redis.yaml
kubectl -n redis-system rollout status deploy/redis
helm upgrade eg oci://docker.io/envoyproxy/gateway-helm --version v1.9.2 \
-n envoy-gateway-system -f eg-values.yaml --wait
kubectl -n envoy-gateway-system get deployErwartet (gekürzt, kann je nach Version abweichen):
deployment "redis" successfully rolled out
Release "eg" has been upgraded. Happy Helming!
NAME READY UP-TO-DATE AVAILABLE AGE
envoy-gateway 1/1 1 1 2d
envoy-infra-web-a97fc3bf 1/1 1 1 2d
envoy-ratelimit 1/1 1 1 30s
envoy-ratelimit ist der Rate-Limit-Dienst, den Envoy
Gateway selbst ausrollt, sobald ein Redis-Backend konfiguriert ist.
Jetzt bekommt das Gateway zwei Envoy-Replikas mit Ressourcen. Die
Tag-9-Werte (IP, externalTrafficPolicy) bleiben drin –
EnvoyProxy ersetzt, es ergänzt nicht:
spec:
provider:
type: Kubernetes
kubernetes:
envoyDeployment:
replicas: 2
container:
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {memory: 512Mi}
envoyService:
type: LoadBalancer
externalTrafficPolicy: Cluster # Pflicht mit Cilium L2
annotations:
lbipam.cilium.io/ips: 10.10.20.100kubectl apply -f envoyproxy-web.yaml
kubectl -n envoy-gateway-system get pods -o wide \
-l gateway.envoyproxy.io/owning-gateway-name=webErwartet (gekürzt, kann je nach Version abweichen):
NAME READY STATUS NODE
envoy-infra-web-a97fc3bf-6c9d8f7b5c-7xq2p 2/2 Running rke2-wk-1
envoy-infra-web-a97fc3bf-6c9d8f7b5c-kd8lm 2/2 Running rke2-wk-3
Tipp: Statt fester
replicasgeht auchenvoyHpa– das zeigt Tag 12. Beides zusammen nicht: Der HPA würdereplicasüberschreiben.
Fortschritt speichern? Kostenlos registrieren
Drill 2: ClientTrafficPolicy – Timeouts, HTTP/2, Client-IP
cat ctp-web.yamlErwartet:
# ClientTrafficPolicy: Verhalten zwischen Client und Envoy (Gateway web)
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
name: web-clients
namespace: infra
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: Gateway
name: web
timeout:
http:
requestReceivedTimeout: 10s # ganze Anfrage inkl. Body
idleTimeout: 60s # Keep-Alive ohne Requests
http2:
maxConcurrentStreams: 100
clientIPDetection:
xForwardedFor:
trustedCIDRs: # nur dieser Proxy darf XFF setzen
- 10.10.20.1/32trustedCIDRs und numTrustedHops schließen
sich aus (CEL-Regel der CRD). Mit trustedCIDRs übernimmt
Envoy einen X-Forwarded-For-Eintrag nur, wenn er von einem
vertrauten Proxy stammt – ein selbst gesetzter Header vom Laptop zählt
nicht.
kubectl apply -f ctp-web.yaml
~/gw-lab/code/demo/conds.sh clienttrafficpolicy web-clients infra
curl -s -H 'X-Forwarded-For: 203.0.113.7' http://shop.apps.lab.internal/ \
| jq -c '{xff: .headers["X-Forwarded-For"],
ext: .headers["X-Envoy-External-Address"]}'Erwartet (gekürzt, kann je nach Version abweichen):
ancestor infra/web/:
Accepted=True (Accepted): Policy has been accepted.
{"xff":["203.0.113.7,10.10.20.21"],"ext":["10.10.20.21"]}
Zwei Lektionen: Die gespoofte 203.0.113.7 wird nicht als
Client-IP übernommen. Und Envoy sieht 10.10.20.21 statt
deiner Laptop-IP – Cilium leitet mit
externalTrafficPolicy: Cluster per SNAT weiter, wenn der
Envoy-Pod nicht auf dem Node mit der L2-Lease läuft. IP-basierte Regeln
(Drill 5) brauchen deshalb Bedacht.
Tipp: Die echte Client-IP bekommst du mit einem vorgeschalteten Proxy (HAProxy auf OPNsense) plus Proxy Protocol (
proxyProtocolin der ClientTrafficPolicy) oder mit Cilium-DSR-Modus bei Native Routing.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Lokales Rate Limit
Ein lokales Limit zählt pro Envoy-Pod – ohne Redis, aber mit zwei Replikas effektiv doppelt so großzügig.
cat btp-shop-local.yamlErwartet:
# BackendTrafficPolicy Stufe 1: lokales Rate Limit (pro Envoy-Pod)
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: BackendTrafficPolicy
metadata:
name: shop
namespace: shop
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: shop
rateLimit:
local:
rules:
- limit:
requests: 10
unit: Secondkubectl apply -f btp-shop-local.yaml
for i in $(seq 1 40); do
curl -s -o /dev/null -w '%{http_code}\n' http://shop.apps.lab.internal/
done | sort | uniq -cErwartet (gekürzt, kann je nach Version abweichen):
22 200
18 429
Warum mehr als 10 Erfolge? Die 40 Requests verteilen sich auf zwei Envoy-Pods mit je eigenem Token-Bucket. Für ein hartes, clusterweites Limit brauchst du das globale Rate Limit.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Globales Rate Limit, Retries, Circuit Breaker, Health Checks
btp-shop-full.yaml ersetzt die Policy shop
(gleicher Name) – pro Route gibt es nur eine BackendTrafficPolicy:
rateLimit:
global:
rules:
- clientSelectors:
- sourceCIDR:
type: Distinct # eigener Zaehler je Client-IP
value: 0.0.0.0/0
limit:
requests: 30
unit: Minute
retry:
numRetries: 2
retryOn:
triggers: [connect-failure, reset, retriable-status-codes]
httpStatusCodes: [503]
perRetry:
timeout: 2s
backOff:
baseInterval: 100ms
maxInterval: 1s
circuitBreaker:
maxConnections: 64
maxPendingRequests: 8
maxParallelRequests: 32
healthCheck:
active:
type: HTTP
interval: 5s
timeout: 1s
unhealthyThreshold: 2
healthyThreshold: 1
http:
path: /health
expectedStatuses: [200]
passive:
consecutive5XxErrors: 3
interval: 10s
baseEjectionTime: 30s
maxEjectionPercent: 50kubectl apply -f btp-shop-full.yaml
~/gw-lab/code/demo/conds.sh backendtrafficpolicy shop shop
for i in $(seq 1 40); do
curl -s -o /dev/null -w '%{http_code}\n' http://shop.apps.lab.internal/
done | sort | uniq -c
curl -sI http://shop.apps.lab.internal/ | grep -i '^x-ratelimit'Erwartet (gekürzt, kann je nach Version abweichen):
ancestor infra/web/:
Accepted=True (Accepted): Policy has been accepted.
30 200
10 429
x-ratelimit-limit: 30, 30;w=60
x-ratelimit-remaining: 0
x-ratelimit-reset: 41
Jetzt exakt 30: Beide Envoy-Pods fragen denselben Zähler in Redis ab. Die Resilienz-Teile prüfst du am Backend-Cluster in der Envoy-Konfiguration:
pod=$(kubectl -n envoy-gateway-system get pod -o name \
-l gateway.envoyproxy.io/owning-gateway-name=web | head -1)
kubectl -n envoy-gateway-system port-forward "$pod" 19000:19000 &
sleep 2
curl -s localhost:19000/clusters | grep -E 'shop/shop.*(max_pending|health_flags)' \
| head -3
kill %1Erwartet (gekürzt, kann je nach Version abweichen):
httproute/shop/shop/rule/0::default_priority::max_pending_requests::8
httproute/shop/shop/rule/0::10.42.4.17:3000::health_flags::healthy
Fällt ein Pod aus der aktiven Prüfung (/health), steht
dort /failed_active_hc; nach drei 5xx in Folge wirft die
passive Prüfung (Outlier Detection) ihn für 30 s raus.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Basic Auth und IP-Allow-List für /admin
kubectl apply -f routes-tag10.yaml
htpasswd -nbs admin lab-admin-1234 > .htpasswd # Lab-Wert!
kubectl -n shop create secret generic shop-admin-users \
--from-file=.htpasswd
cat sp-admin.yamlErwartet:
# Basic Auth + IP-Allow-List fuer /admin (Secret: siehe Drill 5)
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
name: shop-admin
namespace: shop
spec:
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: shop-admin
basicAuth:
users:
name: shop-admin-users # Key .htpasswd, {SHA}-Hashes
forwardUsernameHeader: X-Auth-User
authorization:
defaultAction: Deny
rules:
- name: heimnetz
action: Allow
principal:
clientCIDRs:
- 10.10.20.0/24
- 192.168.178.0/24 # Laptop-Netz anpassenEnvoy Gateway akzeptiert im .htpasswd nur SHA-Hashes –
deshalb htpasswd -s. Die Allow-List umfasst das Lab-Netz
(SNAT-Fall aus Drill 2) und dein Laptop-Netz.
kubectl apply -f sp-admin.yaml
U=http://shop.apps.lab.internal/admin
curl -s -o /dev/null -w '%{http_code}\n' $U
curl -s -u admin:lab-admin-1234 $U | jq -r '.headers["X-Auth-User"][0]'
kubectl run probe --rm -i --restart=Never -q \
--image=curlimages/curl -- \
curl -s -o /dev/null -w '%{http_code}\n' -u admin:lab-admin-1234 $UErwartet (gekürzt, kann je nach Version abweichen):
401
admin
403
Der Pod im Cluster kommt mit seiner Pod-IP (10.42.x.x) –
trotz richtigem Passwort gilt defaultAction: Deny.
Authentifizierung und Autorisierung sind zwei getrennte Prüfungen.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Keycloak und JWT für die API
Keycloak läuft im Lab im Dev-Modus mit importiertem Realm
lab (Clients portal und
api-client, User thomas) hinter dem Gateway
unter https://keycloak.apps.lab.internal:
kubectl apply -f keycloak.yaml
kubectl -n keycloak rollout status deploy/keycloak --timeout=5m
CA=~/gw-lab/tag09/rke2-lab-ca.crt
curl -s --cacert $CA \
https://keycloak.apps.lab.internal/realms/lab/.well-known/openid-configuration \
| jq -r .issuerErwartet (gekürzt, kann je nach Version abweichen):
deployment "keycloak" successfully rolled out
https://keycloak.apps.lab.internal/realms/lab
Envoy muss die JWKS per HTTPS holen und dabei der Lab-CA vertrauen.
Das erledigen ein Backend (FQDN) und eine
BackendTLSPolicy:
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
name: keycloak
namespace: shop
spec:
endpoints:
- fqdn:
hostname: keycloak.apps.lab.internal
port: 443
---
apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
name: keycloak
namespace: shop
spec:
targetRefs:
- group: gateway.envoyproxy.io
kind: Backend
name: keycloak
validation:
hostname: keycloak.apps.lab.internal
caCertificateRefs:
- group: ""
kind: ConfigMap
name: lab-cakubectl -n shop create configmap lab-ca --from-file=ca.crt=$CA
kubectl apply -f keycloak-backend.yaml -f sp-api-jwt.yaml
~/gw-lab/code/demo/conds.sh securitypolicy api-jwt shopErwartet (gekürzt, kann je nach Version abweichen):
ancestor infra/web/:
Accepted=True (Accepted): Policy has been accepted.
Die Policy prüft Issuer und Signatur und reicht den Claim
azp als X-Client-Id weiter. Token per
Client-Credentials holen und testen:
TOKEN=$(curl -s --cacert $CA \
https://keycloak.apps.lab.internal/realms/lab/protocol/openid-connect/token \
-d grant_type=client_credentials -d client_id=api-client \
-d client_secret=lab-api-secret-1234 | jq -r .access_token)
A=https://api.apps.lab.internal/
curl -s -o /dev/null -w '%{http_code}\n' --cacert $CA $A
curl -s --cacert $CA -H "Authorization: Bearer $TOKEN" $A \
| jq -c '{service, client: .headers["X-Client-Id"]}'
curl -s -o /dev/null -w '%{http_code}\n' --cacert $CA \
-H "Authorization: Bearer ${TOKEN%?}x" $AErwartet (gekürzt, kann je nach Version abweichen):
401
{"service":"shop-v2","client":["api-client"]}
401
Tipp: Envoy-Pods lösen
keycloak.apps.lab.internalüber CoreDNS und den DNS-Server der Nodes auf. Zeigtdns_serveraus Tag 8 nicht auf den Resolver mit dem Wildcard-Eintrag (Tag 9), bleibt die Policy mitResolvedRefs-Fehlern hängen.
Fortschritt speichern? Kostenlos registrieren
Drill 7: OIDC-Login für das Portal und CORS
Das Portal bekommt einen echten Browser-Login (Authorization Code Flow); Envoy hält die Session im Cookie:
kubectl -n shop create secret generic portal-oidc \
--from-literal=client-secret=lab-portal-secret-1234
kubectl apply -f sp-portal-oidc.yaml
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' --cacert $CA \
https://portal.apps.lab.internal/Erwartet (gekürzt, kann je nach Version abweichen):
302 https://keycloak.apps.lab.internal/realms/lab/protocol/openid-connect/auth
?client_id=portal&redirect_uri=https%3A%2F%2Fportal.apps.lab.internal%2Foauth2
%2Fcallback&response_type=code&scope=openid+email&state=...
Im Browser (Lab-CA importiert) landest du nach dem Login als
thomas / lab-pass-1234 auf
shop-v1. /logout beendet die Session.
CORS regelt, welche fremden Web-Origins die Shop-API aus dem Browser aufrufen dürfen:
kubectl apply -f sp-cors.yaml
for o in https://portal.apps.lab.internal https://evil.example; do
curl -s -o /dev/null -D - -X OPTIONS http://shop.apps.lab.internal/ \
-H "Origin: $o" -H 'Access-Control-Request-Method: POST' \
| grep -i '^access-control-allow-origin' || echo "kein CORS für $o"
doneErwartet (gekürzt, kann je nach Version abweichen):
access-control-allow-origin: https://portal.apps.lab.internal
kein CORS für https://evil.example
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
export KUBECONFIG=~/.kube/rke2-lab.yaml
CA=~/gw-lab/tag09/rke2-lab-ca.crt
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
acc() { kubectl -n "$1" get "$2" "$3" -o \
jsonpath='{.status.ancestors[0].conditions[?(@.type=="Accepted")].status}' \
| grep -q True; }
check "2 Envoy-Replikas" \
'[ "$(kubectl -n envoy-gateway-system get pods --no-headers \
-l gateway.envoyproxy.io/owning-gateway-name=web | wc -l)" -eq 2 ]'
check "ClientTrafficPolicy akzeptiert" 'acc infra clienttrafficpolicy web-clients'
check "BackendTrafficPolicy akzeptiert" 'acc shop backendtrafficpolicy shop'
for sp in shop-admin shop-cors api-jwt portal-oidc; do
check "SecurityPolicy $sp akzeptiert" "acc shop securitypolicy $sp"
done
check "/admin ohne Login = 401" \
'[ "$(curl -s -o /dev/null -w "%{http_code}" \
http://shop.apps.lab.internal/admin)" = 401 ]'
check "API ohne Token = 401" \
'[ "$(curl -s -o /dev/null -w "%{http_code}" --cacert $CA \
https://api.apps.lab.internal/)" = 401 ]'
check "Portal leitet zu Keycloak" \
'curl -s -o /dev/null -w "%{redirect_url}" --cacert $CA \
https://portal.apps.lab.internal/ | grep -q keycloak.apps.lab.internal'Challenge
Nur der Client api-client darf die API nutzen. Ein
gültiges Token eines anderen Clients aus dem Realm lab
(etwa portal) soll 403 bekommen.
Hinweis:
authorization.rules[].principal.jwt prüft Claims, sobald im
selben SecurityPolicy-Objekt ein jwt-Provider definiert
ist.
Lösung
kubectl -n shop patch securitypolicy api-jwt --type=merge -p '
spec:
authorization:
defaultAction: Deny
rules:
- name: nur-api-client
action: Allow
principal:
jwt:
provider: keycloak
claims:
- name: azp
values: [api-client]
'
PTOKEN=$(curl -s --cacert $CA \
https://keycloak.apps.lab.internal/realms/lab/protocol/openid-connect/token \
-d grant_type=password -d client_id=portal \
-d client_secret=lab-portal-secret-1234 \
-d username=thomas -d password=lab-pass-1234 | jq -r .access_token)
for t in "$TOKEN" "$PTOKEN"; do
curl -s -o /dev/null -w '%{http_code}\n' --cacert $CA \
-H "Authorization: Bearer $t" https://api.apps.lab.internal/
doneErwartet (gekürzt, kann je nach Version abweichen):
200
403
Der Password-Grant ist im Lab-Realm für portal bewusst
erlaubt (directAccessGrantsEnabled). In Produktion bleibt
er aus, getestet wird mit dem Browser-Flow.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Keycloak produktiv mit Postgres, mehreren Replikas und eigenem Hostname; Realm-Konfiguration per GitOps (keycloak-config-cli), Client-Secrets aus Vault/OpenBao.
- Globales Rate Limit braucht hochverfügbares Redis (Sentinel/Cluster) mit Auth und TLS; teste bewusst, was bei einem Redis-Ausfall mit den Requests passiert.
- Policies nach Rollen trennen: Plattform-Team besitzt
ClientTrafficPolicyundEnvoyProxy, App-TeamsSecurityPolicy/BackendTrafficPolicyan ihren Routes (RBAC aus Tag 7). - Client-IP-Regeln nur mit verlässlicher Quelle (Proxy Protocol, DSR); sonst lieber Identität (JWT, mTLS) statt IP.
- Basic Auth nur als Notlösung; SHA-1-Hashes sind schwach – besser
OIDC oder
extAuthgegen einen zentralen Auth-Dienst.