Tag 4: TLS – cert-manager, HTTPS-Redirect, SNI, Passthrough, BackendTLSPolicy
Ziel: Das Gateway spricht HTTPS mit Zertifikaten aus der Lab-CA, leitet HTTP um und verschlüsselt bis ins Backend. · Dauer: ca. 75 min · Voraussetzung: Tag 3
Briefing
- TLS gehört an den Listener:
protocol: HTTPS,tls.mode: Terminate,certificateRefsauf ein Secret im Namespace des Gateways. - cert-manager liest die Annotation
cert-manager.io/cluster-issueram Gateway und erzeugt pro Listener ein Certificate (gateway-shim) – kein Ingress-Annotation-Zoo mehr. - Mehrere HTTPS-Listener auf Port 443 mit verschiedenen Hostnames = SNI. Envoy wählt das Zertifikat anhand des Servernamens.
Passthrough+ TLSRoute: Envoy schaut nur auf SNI und reicht verschlüsselt durch. BackendTLSPolicy (v1): Gateway → Backend wieder mit TLS.
curl ──TLS(shop)──> Listener https-shop ──HTTP──> shop-v1
curl ──TLS(api)───> Listener https-api ──TLS (BackendTLSPolicy)──> secure:443
curl ──TLS(secure)> Listener tls-secure ──unverändert (Passthrough)──> secure:443
curl ──HTTP:80────> Listener http ──301──> https://...
Drill 1: cert-manager mit Gateway-API-Support
mkdir -p ~/gw-lab/tag04 && cd ~/gw-lab/tag04
export GW_IP=$(gw-ip.sh)
helm upgrade --install cert-manager oci://quay.io/jetstack/charts/cert-manager \
--version v1.21.2 -n cert-manager --create-namespace \
--set crds.enabled=true \
--set config.gatewayAPI.enabled=true \
--wait
kubectl -n cert-manager get deploy
kubectl -n cert-manager logs deploy/cert-manager \
| grep -o 'enabling the sig-network.*shim'Erwartet (gekürzt):
NAME READY UP-TO-DATE AVAILABLE AGE
cert-manager 1/1 1 1 62s
cert-manager-cainjector 1/1 1 1 62s
cert-manager-webhook 1/1 1 1 62s
enabling the sig-network Gateway API certificate-shim
config.gatewayAPI.enabled schaltet den gateway-shim ein.
Die Gateway-API-CRDs müssen vor dem Start von cert-manager existieren –
bei uns liefert sie Envoy Gateway (Tag 1).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Die Lab-CA
Eine selbstsignierte Root, daraus der
ClusterIssuer lab-ca:
cat > lab-ca.yaml <<'EOF'
# Lab-CA: selbstsignierte Root, daraus ClusterIssuer lab-ca (nur Lab!)
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: selfsigned
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: lab-ca
namespace: cert-manager
spec:
isCA: true
commonName: gw-lab Root CA
secretName: lab-ca
duration: 87600h
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: selfsigned
kind: ClusterIssuer
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: lab-ca
spec:
ca:
secretName: lab-ca
EOF
kubectl apply -f lab-ca.yaml
kubectl wait clusterissuer/lab-ca --for=condition=Ready --timeout=60s
kubectl -n cert-manager get secret lab-ca -o jsonpath='{.data.ca\.crt}' \
| base64 -d > lab-ca.crt
openssl x509 -in lab-ca.crt -noout -subject -enddateErwartet:
clusterissuer.cert-manager.io/selfsigned created
certificate.cert-manager.io/lab-ca created
clusterissuer.cert-manager.io/lab-ca created
clusterissuer.cert-manager.io/lab-ca condition met
subject=CN=gw-lab Root CA
notAfter=Oct 7 05:34:08 2036 GMT
Tipp:
failed calling webhook ... x509: certificate signed by unknown authoritydirekt nach der Installation? Der Webhook bekommt sein CA-Bundle erst nach einigen Sekunden. 30 s warten, dannkubectl applywiederholen.
lab-ca.crt ist ab jetzt dein Trust-Anker für
curl --cacert.
Sicherheit: Die Lab-CA ist ein Lab-Wert. Nie in einen System-Truststore importieren.
Fortschritt speichern? Kostenlos registrieren
Drill 3: HTTPS-Listener mit gateway-shim
Das Plattform-Team ersetzt das Gateway web: Port 80
bleibt, dazu zwei HTTPS-Listener. Den Listener http-api aus
Tag 2 brauchst du nicht mehr – HTTP wird gleich umgeleitet.
cat > gateway-https.yaml <<'EOF'
# Gateway web mit HTTPS-Listenern; cert-manager erzeugt die Secrets
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
name: web
namespace: infra
annotations:
cert-manager.io/cluster-issuer: lab-ca
spec:
gatewayClassName: eg
listeners:
- name: http
protocol: HTTP
port: 80
allowedRoutes:
namespaces:
from: All
- name: https-shop
protocol: HTTPS
port: 443
hostname: shop.gw.localtest.me
tls:
mode: Terminate
certificateRefs:
- name: shop-gw-tls
allowedRoutes:
namespaces:
from: All
- name: https-api
protocol: HTTPS
port: 443
hostname: api.gw.localtest.me
tls:
mode: Terminate
certificateRefs:
- name: api-gw-tls
allowedRoutes:
namespaces:
from: All
EOF
kubectl apply -f gateway-https.yaml
sleep 20
kubectl -n infra get certificate
kubectl -n infra get certificate shop-gw-tls \
-o jsonpath='{.spec.dnsNames} {.spec.issuerRef.name}{"\n"}'
conds.sh gateway web infra | grep -A3 https-shopErwartet:
gateway.gateway.networking.k8s.io/web configured
NAME READY SECRET AGE
api-gw-tls True api-gw-tls 20s
shop-gw-tls True shop-gw-tls 20s
["shop.gw.localtest.me"] lab-ca
listener https-shop (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
Der Shim baut aus hostname den SAN und aus
certificateRefs[0].name den Secret-Namen. Ohne
hostname oder bei mode: Passthrough erzeugt er
nichts. In den ersten Sekunden steht ResolvedRefs=False –
das Secret existiert dann noch nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Routen auf HTTPS umhängen und SNI prüfen
cat > routes-https.yaml <<'EOF'
# Shop- und API-Route hängen jetzt an den HTTPS-Listenern
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: shop
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: https-shop
hostnames:
- shop.gw.localtest.me
rules:
- backendRefs:
- name: shop-v1
port: 80
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: api
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: https-api
rules:
- backendRefs:
- name: shop-v2
port: 80
EOF
kubectl apply -f routes-https.yaml
s() { # s <host> [pfad] [curl-Optionen ...]
curl -s --cacert lab-ca.crt --resolve "$1:443:$GW_IP" "${@:3}" "https://$1${2:-/}"
}
s shop.gw.localtest.me | jq -r '.service + " " + .headers["X-Forwarded-Proto"][0]'
s api.gw.localtest.me | jq -r .serviceErwartet:
httproute.gateway.networking.k8s.io/shop configured
httproute.gateway.networking.k8s.io/api created
shop-v1 https
shop-v2
Welches Zertifikat liefert Envoy für welchen Servernamen?
for h in shop api; do
openssl s_client -connect "$GW_IP:443" -servername $h.gw.localtest.me \
</dev/null 2>/dev/null | openssl x509 -noout -ext subjectAltName
done
curl -s --cacert lab-ca.crt --resolve foo.gw.localtest.me:443:$GW_IP \
https://foo.gw.localtest.me/; echo "Exit: $?"Erwartet:
X509v3 Subject Alternative Name: critical
DNS:shop.gw.localtest.me
X509v3 Subject Alternative Name: critical
DNS:api.gw.localtest.me
Exit: 35
Exit 35 = TLS-Fehler: Für den Servernamen foo gibt es
keinen Listener, Envoy bricht den Handshake ab, bevor überhaupt ein
HTTP-Request existiert.
Fortschritt speichern? Kostenlos registrieren
Drill 5: HTTP → HTTPS umleiten
Port 80 hat gerade keine Route mehr – jeder Request endet mit 404. Eine Route des Plattform-Teams ohne Hostname fängt alles ab:
cat > https-redirect.yaml <<'EOF'
# Alles auf Port 80 -> 301 auf HTTPS (gehört dem Plattform-Team)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: https-redirect
namespace: infra
spec:
parentRefs:
- name: web
sectionName: http
rules:
- filters:
- type: RequestRedirect
requestRedirect:
scheme: https
statusCode: 301
EOF
kubectl apply -f https-redirect.yaml
curl -si --resolve shop.gw.localtest.me:80:$GW_IP \
'http://shop.gw.localtest.me/warenkorb?id=7' | head -2
curl -sL --cacert lab-ca.crt --resolve shop.gw.localtest.me:80:$GW_IP \
--resolve shop.gw.localtest.me:443:$GW_IP http://shop.gw.localtest.me/warenkorb \
| jq -r '.path + " " + .service'Erwartet:
httproute.gateway.networking.k8s.io/https-redirect created
HTTP/1.1 301 Moved Permanently
location: https://shop.gw.localtest.me/warenkorb?id=7
/warenkorb shop-v1
Pfad und Query bleiben erhalten, nur das Schema wechselt; der Port
springt auf den Default 443. Das ersetzt
nginx.ingress.kubernetes.io/ssl-redirect.
Fortschritt speichern? Kostenlos registrieren
Drill 6: TLS-Passthrough mit TLSRoute
Manche Backends wollen TLS selbst terminieren (mTLS zum Client, eigene Zertifikate). Dafür ein Backend, das selbst HTTPS auf 8443 spricht. Sein Zertifikat gilt für den externen und den internen Namen – Drill 7 nutzt es wieder.
Das Deployment (echo-basic mit
TLS_SERVER_CERT/TLS_SERVER_PRIVKEY, Port 8443)
und den Service secure:443 findest du im Begleitcode unter
~/gw-lab/code/tag04/secure-backend.yaml. Neu ist nur das
Zertifikat:
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: secure-backend
namespace: shop
spec:
secretName: secure-backend-tls # wird ins Pod-Volume /tls gemountet
dnsNames:
- secure.gw.localtest.me # extern, für Passthrough (Drill 6)
- secure.shop.svc # intern, für BackendTLSPolicy (Drill 7)
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: lab-ca
kind: ClusterIssuerkubectl apply -f ~/gw-lab/code/tag04/secure-backend.yaml
kubectl -n shop wait certificate/secure-backend --for=condition=Ready --timeout=60s
kubectl -n shop rollout status deploy/secure --timeout=90sErwartet (gekürzt):
certificate.cert-manager.io/secure-backend condition met
deployment "secure" successfully rolled out
Jetzt der Passthrough-Listener (Port 8443,
protocol: TLS) und die TLSRoute:
kubectl -n infra patch gateway web --type=json -p '[{"op":"add",
"path":"/spec/listeners/-","value":{"name":"tls-secure","protocol":"TLS",
"port":8443,"hostname":"secure.gw.localtest.me","tls":{"mode":"Passthrough"},
"allowedRoutes":{"namespaces":{"from":"All"}}}}]'
cat > tlsroute.yaml <<'EOF'
# TLS-Passthrough: Envoy schaut nur auf SNI, entschlüsselt nicht
apiVersion: gateway.networking.k8s.io/v1
kind: TLSRoute
metadata:
name: secure
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: tls-secure
hostnames:
- secure.gw.localtest.me
rules:
- backendRefs:
- name: secure
port: 443
EOF
kubectl apply -f tlsroute.yaml
conds.sh tlsroute secure shop
curl -s --cacert lab-ca.crt --resolve secure.gw.localtest.me:8443:$GW_IP \
https://secure.gw.localtest.me:8443/ \
| jq -c '{service, xfp: .headers["X-Forwarded-Proto"], tls: .tls.serverName}'Erwartet:
gateway.gateway.networking.k8s.io/web patched
tlsroute.gateway.networking.k8s.io/secure created
parent infra/web/tls-secure:
Accepted=True (Accepted): Route is accepted
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references for the Route
{"service":"secure","xfp":null,"tls":"secure.gw.localtest.me"}
Der Beweis: Kein X-Forwarded-Proto – Envoy hat keinen
HTTP-Request gesehen. Das Backend selbst meldet den TLS-Handshake mit
SNI secure.gw.localtest.me.
Achtung: Bei Passthrough gibt es keine HTTP-Filter, keine Header, keine Pfade. Routing nur über SNI. Der Shim erzeugt hier kein Zertifikat.
Fortschritt speichern? Kostenlos registrieren
Drill 7: BackendTLSPolicy – verschlüsselt bis zum Pod
Gleiches Backend, diesmal terminiert das Gateway und baut eine neue TLS-Verbindung auf. Zuerst die Route ohne Policy:
cat > secure-api.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: secure-api
namespace: shop
spec:
parentRefs:
- name: web
namespace: infra
sectionName: https-api
rules:
- matches:
- path: {type: PathPrefix, value: /secure}
backendRefs:
- name: secure
port: 443
EOF
kubectl apply -f secure-api.yaml
s api.gw.localtest.me /secure -o /dev/null -w '%{http_code}\n'Erwartet:
httproute.gateway.networking.k8s.io/secure-api created
400
400: Envoy spricht Klartext-HTTP mit einem HTTPS-Server. Die Policy hängt am Service, die CA kommt als ConfigMap in denselben Namespace:
kubectl -n shop create configmap lab-ca --from-file=ca.crt=lab-ca.crt
cat > backend-tls.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
name: secure
namespace: shop
spec:
targetRefs:
- group: ""
kind: Service
name: secure
sectionName: https
validation:
caCertificateRefs:
- group: ""
kind: ConfigMap
name: lab-ca
hostname: secure.shop.svc
EOF
kubectl apply -f backend-tls.yaml
sleep 5
s api.gw.localtest.me /secure | jq -c '{service, sni: .tls.serverName}'
conds.sh backendtlspolicy secure shop | head -3Erwartet:
configmap/lab-ca created
backendtlspolicy.gateway.networking.k8s.io/secure created
{"service":"secure","sni":"secure.shop.svc"}
ancestor infra/web/https-api:
ResolvedRefs=True (ResolvedRefs): Resolved all the Object references.
Accepted=True (Accepted): Policy has been accepted.
hostname ist Pflicht: Envoy schickt ihn als SNI und
prüft das Backend-Zertifikat dagegen. Gegenprobe mit falschem Namen:
kubectl -n shop patch backendtlspolicy secure --type=merge \
-p '{"spec":{"validation":{"hostname":"falsch.shop.svc"}}}'
sleep 15
s api.gw.localtest.me /secure -w '\n%{http_code}\n'
kubectl -n shop patch backendtlspolicy secure --type=merge \
-p '{"spec":{"validation":{"hostname":"secure.shop.svc"}}}'Erwartet (gekürzt):
backendtlspolicy.gateway.networking.k8s.io/secure patched
upstream connect error or disconnect/reset before headers. reset reason: remote
connection failure
503
backendtlspolicy.gateway.networking.k8s.io/secure patched
BackendTLSPolicy ist seit Gateway API v1.4 v1 und
Standard. Statt eigener CA geht auch
wellKnownCACertificates: System (öffentliche CAs).
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cd ~/gw-lab/tag04
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
GW_IP=$(gw-ip.sh)
s() { # s <host> [pfad] [curl-Optionen ...]
curl -s --cacert lab-ca.crt --resolve "$1:443:$GW_IP" "${@:3}" "https://$1${2:-/}"
}
check "ClusterIssuer lab-ca Ready" \
'kubectl wait clusterissuer/lab-ca --for=condition=Ready --timeout=5s'
check "Shim-Zertifikate Ready" \
'[ "$(kubectl -n infra get certificate -o name | wc -l)" -ge 2 ]'
check "HTTPS shop -> shop-v1" \
'[ "$(s shop.gw.localtest.me | jq -r .service)" = shop-v1 ]'
check "HTTP -> 301 https" \
'curl -sI --resolve shop.gw.localtest.me:80:$GW_IP http://shop.gw.localtest.me/ \
| grep -qi "^location: https://"'
check "Passthrough ohne X-Forwarded-Proto" \
'curl -s --cacert lab-ca.crt --resolve secure.gw.localtest.me:8443:$GW_IP \
https://secure.gw.localtest.me:8443/ \
| jq -e ".headers[\"X-Forwarded-Proto\"] == null"'
check "BackendTLS SNI secure.shop.svc" \
'[ "$(s api.gw.localtest.me /secure | jq -r .tls.serverName)" = secure.shop.svc ]'Erwartet:
✔ ClusterIssuer lab-ca Ready
✔ Shim-Zertifikate Ready
✔ HTTPS shop -> shop-v1
✔ HTTP -> 301 https
✔ Passthrough ohne X-Forwarded-Proto
✔ BackendTLS SNI secure.shop.svc
Challenge
Die Security-Abteilung verlangt für alle Gateway-Zertifikate ECDSA-Schlüssel und eine Laufzeit von 30 Tagen mit Erneuerung nach 20 Tagen. Setze das um, ohne ein einziges Certificate-Objekt von Hand anzulegen.
Hinweis: Der gateway-shim liest außer dem Issuer
noch weitere cert-manager.io/- Annotationen vom
Gateway.
Lösung
kubectl -n infra annotate gateway web --overwrite \
cert-manager.io/private-key-algorithm=ECDSA \
cert-manager.io/private-key-size=256 \
cert-manager.io/duration=720h \
cert-manager.io/renew-before=240h
sleep 5
kubectl -n infra get certificate shop-gw-tls \
-o jsonpath='{.spec.privateKey.algorithm} {.spec.duration} {.spec.renewBefore}{"\n"}'
openssl s_client -connect "$GW_IP:443" -servername shop.gw.localtest.me \
</dev/null 2>/dev/null | openssl x509 -noout -text | grep 'Public Key Algorithm'Erwartet (gekürzt, kann je nach Version abweichen):
gateway.gateway.networking.k8s.io/web annotated
ECDSA 720h0m0s 240h0m0s
Public Key Algorithm: id-ecPublicKey
Bestehende Schlüssel tauscht cert-manager erst beim nächsten
Ausstellen. Erzwingen kannst du es mit
kubectl -n infra delete secret shop-gw-tls.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Statt Lab-CA: ACME (Let’s Encrypt, DNS-01 für Wildcards) oder eine interne PKI wie Vault/OpenBao als Issuer (Tag 9). Die Gateway-Annotation bleibt gleich.
- Wildcard-Listener (
*.apps.example.com) mit einem Zertifikat halten das Gateway klein; pro App eigene Hostnames erst, wenn Teams eigene Zertifikate brauchen (ListenerSet, Tag 7). curl -kundinsecureSkipVerifygehören in kein Runbook. BackendTLSPolicy mithostnameprüfen lassen, CA per ConfigMap/ClusterTrustBundle verteilen.- Passthrough nur, wenn das Backend wirklich selbst terminieren muss: Ohne HTTP-Sicht gibt es keine L7-Policies, kein WAF, keine Access-Logs mit Pfad.
- Zertifikatsablauf überwachen:
certmanager_certificate_expiration_timestamp_secondsaus cert-manager plus ein externer Check (Tag 12).