Zum Inhalt springen
Trainingslager IT-Trainingslager

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 targetRefs an Gateway, Listener oder Route (Policy Attachment) und melden ihren Status in status.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 kubeconform gegen 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.yaml

Erwartet:

# 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 deploy

Erwartet (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.100
kubectl apply -f envoyproxy-web.yaml
kubectl -n envoy-gateway-system get pods -o wide \
  -l gateway.envoyproxy.io/owning-gateway-name=web

Erwartet (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 replicas geht auch envoyHpa – das zeigt Tag 12. Beides zusammen nicht: Der HPA würde replicas überschreiben.

Fortschritt speichern? Kostenlos registrieren

Drill 2: ClientTrafficPolicy – Timeouts, HTTP/2, Client-IP

cat ctp-web.yaml

Erwartet:

# 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/32

trustedCIDRs 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 (proxyProtocol in 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.yaml

Erwartet:

# 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: Second
kubectl 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 -c

Erwartet (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: 50
kubectl 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 %1

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

Erwartet:

# 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 anpassen

Envoy 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 $U

Erwartet (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 .issuer

Erwartet (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-ca
kubectl -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 shop

Erwartet (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" $A

Erwartet (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. Zeigt dns_server aus Tag 8 nicht auf den Resolver mit dem Wildcard-Eintrag (Tag 9), bleibt die Policy mit ResolvedRefs-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"
done

Erwartet (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/
done

Erwartet (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 ClientTrafficPolicy und EnvoyProxy, App-Teams SecurityPolicy/BackendTrafficPolicy an 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 extAuth gegen einen zentralen Auth-Dienst.