Zum Inhalt springen
Trainingslager IT-Trainingslager

Anhang A: Spickzettel

Stand: Gateway API v1.6.1, Envoy Gateway v1.9.2, cert-manager v1.21.2, Cilium 1.20. Namen und Hosts entsprechen dem Lab: Gateway infra/web, GatewayClasses eg und cilium, *.gw.localtest.me in kind, *.apps.lab.internal auf RKE2.

Ressourcenmodell

Ressource API Besitzer Zweck
GatewayClass gateway.networking.k8s.io/v1 Cluster-Operator Implementierung wählen (controllerName)
Gateway .../v1 Plattform-Team Listener: Port, Protokoll, Hostname, TLS
ListenerSet .../v1 (seit v1.5) App-Team eigene Listener an fremdem Gateway
HTTPRoute .../v1 App-Team HTTP nach Host, Pfad, Header, Query, Methode
GRPCRoute .../v1 App-Team gRPC nach Service, Methode, Header
TLSRoute .../v1 (seit v1.5) App-Team TLS-Passthrough nach SNI
TCPRoute, UDPRoute .../v1 (seit v1.6) App-Team L4, nur Listener-Port
ReferenceGrant .../v1 (Storage v1beta1) Besitzer des Ziels Querverweis über Namespaces erlauben
BackendTLSPolicy .../v1 (seit v1.4) App-Team TLS vom Gateway zum Backend
Ingress Gateway API
IngressClass GatewayClass
(im Controller versteckt) Gateway mit Listenern
Ingress-Regeln HTTPRoute, GRPCRoute, TLSRoute …
Annotationen Filter, Regel-Felder, Policies
Channel Inhalt Einsatz
Standard GA-Ressourcen und -Felder Produktion
Experimental Standard plus Alpha-Felder (retry, sessionPersistence) und x-k8s.io-Typen Lab, gezielt

Listener und allowedRoutes

Feld Werte Merke
protocol HTTP, HTTPS, TLS, TCP, UDP HTTPS/TLS brauchen tls
tls.mode Terminate, Passthrough Passthrough nur mit TLSRoute
allowedRoutes.namespaces.from Same, All, Selector Default Same
allowedRoutes.kinds z. B. [GRPCRoute] schränkt Route-Arten ein
allowedListeners (Gateway) wie namespaces erlaubt ListenerSets
infrastructure.parametersRef EnvoyProxy Envoy-Deployment und Service

Route-Matching und Vorrang

Regel Bedeutung
Einträge in einem matches[]-Element UND
mehrere matches[]-Elemente ODER
Regel ohne matches implizit PathPrefix /
PathPrefix /v2 passt auf /v2, /v2/x, nicht /v2x (Segmente)
Header-Namen / -Werte case-insensitiv / case-sensitiv
Route ohne hostnames erbt den Hostname des Listeners
Route- und Listener-Hostname müssen sich überschneiden, sonst NoMatchingListenerHostname

Vorrang bei HTTPRoute, von oben nach unten:

Stufe Kriterium
1 exakter Hostname vor Wildcard
2 Exact vor längstem PathPrefix
3 Methode, dann mehr Header-, dann mehr Query-Matches
4 älteste Route (creationTimestamp)
5 alphabetisch namespace/name

GRPCRoute: exakter Hostname vor Wildcard, dann längster service, dann method, dann Anzahl Header-Matches. Keine passende Methode: gRPC-Status 12 Unimplemented.

Filter und Regel-Felder

Filter / Feld Ersetzt (ingress-nginx) Level
RequestRedirect (scheme, hostname, path, port, statusCode) ssl-redirect, permanent-redirect Core
RequestHeaderModifier (set/add/remove) configuration-snippet Core
ResponseHeaderModifier more_set_headers Extended
URLRewrite (hostname, ReplacePrefixMatch/ReplaceFullPath) rewrite-target, upstream-vhost Extended
RequestMirror (backendRef, percent/fraction) mirror-target Extended
CORS enable-cors, cors-* Extended
ExtensionRef → EG HTTPRouteFilter Regex-Rewrite mit Capture Group Implementierung
rules[].timeouts.request / backendRequest proxy-read-timeout Extended
rules[].retry (codes, attempts, backoff) – Experimental
backendRefs[].weight canary-weight Core
  • Redirect und Rewrite schließen sich in einer Regel aus.
  • ReplacePrefixMatch nur zusammen mit PathPrefix-Match.
  • retry.attempts: 3 = drei Wiederholungen, bis zu vier Versuche.
  • weight: 0 = kein Traffic, aber das Backend bleibt für den Rollback in der Route.

Status-Conditions

Objekt Condition (Reason) Bedeutung
GatewayClass Accepted=Unknown (Pending) kein Controller mit diesem controllerName
Gateway Accepted=True, Programmed=True Spec gültig, Datenebene bereit mit Adresse
Gateway Accepted=True (ListenersNotValid) mindestens ein Listener kaputt, Rest läuft
Listener ResolvedRefs=False (InvalidCertificateRef) Secret fehlt oder ungültig
Listener ResolvedRefs=False (RefNotPermitted) Secret in anderem Namespace ohne ReferenceGrant
Route Accepted=False (NotAllowedByListeners) Namespace/Kind nicht in allowedRoutes
Route Accepted=False (NoMatchingListenerHostname) Hostnames überschneiden sich nicht
Route Accepted=False (NoMatchingParent) sectionName/Port passt zu keinem Listener
Route ResolvedRefs=False (BackendNotFound) Service fehlt; Envoy antwortet 500
Route ResolvedRefs=False (RefNotPermitted) Backend in anderem Namespace ohne ReferenceGrant
Route RouteRulesOverlap=True gleich spezifische Regeln, älteste gewinnt
Policy Accepted=False in status.ancestors Ziel falsch oder Konflikt mit anderer Policy
ListenerSet Accepted=False (NotAllowed) allowedListeners am Gateway verbietet es
(gar kein Status) – Gateway/Parent existiert nicht oder fremder Controller

Immer observedGeneration mit metadata.generation vergleichen: Ist sie kleiner, hat der Controller die aktuelle Spec noch nicht gesehen.

Envoy-Response-Flags (Access Log flags)

Flag Bedeutung Typische Ursache
UH kein gesunder Upstream Service ohne Endpunkte (Canary auf totes v2)
UF Upstream-Verbindung fehlgeschlagen falscher Port, Pod startet
UT Upstream-Timeout timeouts.request überschritten
URX Retry-Limit erreicht retry/numRetries aufgebraucht
RL lokal oder global rate-limitiert (429) BackendTrafficPolicy rateLimit
RLSE Rate-Limit-Dienst nicht erreichbar Redis/envoy-ratelimit weg
NR keine Route Hostname/Pfad ohne Regel (404)
- kein Flag normaler Request oder Direct Response

Envoy-Gateway-Policies und Ziele

Alle gateway.envoyproxy.io/v1alpha1. Pro Ziel und Policy-Art gilt eine Policy; die spezifischere (Route vor Gateway) gewinnt.

Ressource Ziel (targetRefs) Wofür Tag
EnvoyProxy per parametersRef am Gateway Replikas, HPA, PDB, Service, Telemetrie, Shutdown 9–12
ClientTrafficPolicy Gateway, Listener (sectionName) Client-Timeouts, HTTP/2, Client-IP, Proxy Protocol 10
BackendTrafficPolicy Gateway, Route, Regel Rate Limit, Retries, Circuit Breaker, Health Checks 10
SecurityPolicy Gateway, Route, Regel Basic Auth, JWT, OIDC, CORS, IP-Regeln, extAuth 10
HTTPRouteFilter per ExtensionRef aus der Route Regex-Rewrite, Direct Response 13
Backend als backendRef FQDN-/IP-Backends (braucht enableBackend) 10
EnvoyPatchPolicy Gateway rohe xDS-Patches, letzter Ausweg –
BackendTLSPolicy (Gateway API) Service, Backend CA und SNI zum Backend 4, 10
Helm-Wert (config.envoyGateway) Wirkung
rateLimit.backend.redis.url globales Rate Limit, startet envoy-ratelimit
rateLimit.failClosed Default false: Redis weg = kein Limit; true = 500
rateLimit.timeout Default 20 ms zum Rate-Limit-Dienst
extensionApis.enableBackend Backend-CRD aktivieren
extensionManager.backendResources fremde Backend-Arten, z. B. InferencePool

Lab-Skripte und kubectl

# Adresse eines Gateways (Default: web in infra), Conditions kompakt
gw-ip.sh; gw-ip.sh web-cilium infra
conds.sh gatewayclass eg
conds.sh gateway web infra
conds.sh httproute shop shop
conds.sh securitypolicy api-jwt shop        # Policies: status.ancestors
# curl-Muster kind: Name umbiegen, Host-Header und SNI bleiben
GW_IP=$(gw-ip.sh)
curl -s --cacert ~/gw-lab/tag04/lab-ca.crt \
  --resolve shop.gw.localtest.me:443:$GW_IP https://shop.gw.localtest.me/
# RKE2: echtes DNS, eigene Lab-CA
export KUBECONFIG=~/.kube/rke2-lab.yaml
curl -s --cacert ~/gw-lab/tag09/rke2-lab-ca.crt https://shop.apps.lab.internal/
# API-Stand und Felder
kubectl api-resources --api-group=gateway.networking.k8s.io
kubectl explain httproute.spec.rules.filters.type
~/gw-lab/code/tag12/crd-check.sh            # Bundle, Channel, served Versions
# Alle Routen, die einen Hostname beanspruchen
kubectl get httproute -A -o json | jq -r --arg h shop.apps.lab.internal \
  '.items[] | select(.spec.hostnames // [] | index($h))
   | "\(.metadata.namespace)/\(.metadata.name)"'
# Envoy-Pods und Service eines Gateways
kubectl -n envoy-gateway-system get deploy,svc,hpa,pdb \
  -l gateway.envoyproxy.io/owning-gateway-name=web
# Access Log (JSON aus Tag 11): Status, Flags, Route
kubectl -n envoy-gateway-system logs -l gateway.envoyproxy.io/owning-gateway-name=web \
  -c envoy --since=5m | grep '^{' | jq -r '"\(.status) \(.flags) \(.route)"' \
  | sort | uniq -c

egctl

egctl version --remote=false
egctl x status all -A --quiet | grep -v True       # nur Auffälliges
egctl x status httproute -n shop
# Was Envoy wirklich hat (Pod-Name ohne "pod/")
POD=$(kubectl -n envoy-gateway-system get pod -o name \
  -l gateway.envoyproxy.io/owning-gateway-name=web | head -1); POD=${POD#pod/}
egctl config envoy-proxy route -n envoy-gateway-system "$POD"
egctl config envoy-proxy cluster -n envoy-gateway-system "$POD"
egctl config envoy-gateway all -n envoy-gateway-system
egctl x dashboard envoy-proxy -n envoy-gateway-system "$POD"   # Admin-UI

Envoy-Clusternamen: httproute/<ns>/<name>/rule/<n>, grpcroute/<ns>/<name>/rule/<n>. Envoy-Deployment: envoy-<namespace>-<gateway>-<hash> im Namespace envoy-gateway-system, für infra/web also envoy-infra-web-a97fc3bf.

cert-manager

Annotation am Gateway Wirkung
cert-manager.io/cluster-issuer: lab-ca Certificate pro HTTPS-Listener (gateway-shim)
cert-manager.io/private-key-algorithm, -size z. B. ECDSA, 256
cert-manager.io/duration, renew-before z. B. 720h, 240h

Voraussetzungen: config.gatewayAPI.enabled=true, Gateway-API-CRDs vor dem Start von cert-manager, Listener mit hostname und tls.mode: Terminate. Secret-Name = certificateRefs[0].name, SAN = Listener-Hostname.

kubectl wait clusterissuer/lab-ca --for=condition=Ready --timeout=60s
kubectl -n infra get certificate
cmctl status certificate -n infra apps-wildcard-tls
cmctl renew -n infra apps-wildcard-tls          # Rotation erzwingen
~/gw-lab/code/tag12/cert-check.sh               # ausgeliefert = Secret?
openssl s_client -connect 10.10.20.100:443 -servername shop.apps.lab.internal \
  </dev/null 2>/dev/null | openssl x509 -noout -subject -enddate -checkend 1209600

Cilium LB-IPAM und L2

Objekt / Feld Lab-Wert Merke
CiliumLoadBalancerIPPool (cilium.io/v2) lab-pool, .100–.120 kubectl get ippools
CiliumL2AnnouncementPolicy (v2alpha1) lab-l2, nur Worker, ^eth0$ mind. zwei Kandidaten
Annotation lbipam.cilium.io/ips .100 web, .101 web-cilium, .110 legacy feste IP pro Service
externalTrafficPolicy Cluster mit L2 Pflicht (Tag 9)
Lease cilium-l2announce-<ns>-<svc> in kube-system Halter = ARP-Antworter
kubectl get ippools
kubectl -n kube-system get lease | grep l2announce
kubectl get ciliuml2announcementpolicy lab-l2 -o yaml
arping -c 2 10.10.20.100                       # MAC = Lease-Halter
kubectl -n kube-system exec ds/cilium -c cilium-agent -- cilium-dbg status \
  | grep KubeProxyReplacement

PromQL

# RPS pro Route-Regel
sum by (envoy_cluster_name) (rate(envoy_cluster_upstream_rq_total{
  envoy_cluster_name=~"httproute/.*"}[5m]))
# 5xx-Quote
sum by (envoy_cluster_name) (rate(envoy_cluster_upstream_rq_xx{
  envoy_response_code_class="5"}[5m]))
/ sum by (envoy_cluster_name) (rate(envoy_cluster_upstream_rq_xx[5m]))
# p95 in Millisekunden
histogram_quantile(0.95, sum by (envoy_cluster_name, le) (
  rate(envoy_cluster_upstream_rq_time_bucket[5m])))
# Zertifikat aus Sicht von Envoy
min(envoy_server_days_until_first_cert_expiring) < 14
# Status über kube-state-metrics (Custom Resource State, Tag 11)
gatewayapi_gateway_status{type="Programmed"} == 0
gatewayapi_httproute_accepted == 0
# Controller: xDS abgelehnt
increase(xds_nack_total[10m]) > 0

Recording Rules aus Tag 11: route:rps:rate5m, route:error5xx:ratio5m, route:latency:p95_5m. Alerts: GatewayNotProgrammed, HTTPRouteNotAccepted, RouteHigh5xx, EnvoyGatewayXdsNack.

ingress2gateway

ingress2gateway print --providers=ingress-nginx -n shop --no-color > out.yaml
ingress2gateway print --providers=ingress-nginx --input-file legacy-ingress.yaml -A
ingress2gateway print --providers=ingress-nginx -n shop --emitter envoy-gateway
ingress2gateway print --providers=traefik --input-file traefik-ingress.yaml -A
ingress-nginx-Annotation Gateway API / Envoy Gateway i2gw
canary, canary-weight, canary-by-header backendRefs[].weight, Header-matches ja
rewrite-target ohne / mit $1 URLRewrite / EG HTTPRouteFilter ja / nein
use-regex RegularExpression, besser PathPrefix ja
ssl-redirect, permanent-redirect RequestRedirect ja
enable-cors, cors-* Filter CORS ja
proxy-*-timeout timeouts (Wert prüfen!) teils
proxy-body-size EG BackendTrafficPolicy.requestBuffer Emitter
whitelist-source-range EG SecurityPolicy.authorization Emitter
auth-url, auth-type: basic EG SecurityPolicy.extAuth / basicAuth nein
limit-rps EG BackendTrafficPolicy.rateLimit nein
backend-protocol: GRPC GRPCRoute ja
ssl-passthrough TLSRoute + Passthrough-Listener ja
*-snippet Filter oder EnvoyPatchPolicy, Einzelfall nein

Ablauf: Inventur → konvertieren → nachbearbeiten → parallel betreiben (--resolve auf beide IPs) → DNS umschalten (TTL vorher senken) → beobachten → Rückbau. Rollback bis zuletzt: DNS-Eintrag zurück auf 10.10.20.110.