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.