Zum Inhalt springen
Trainingslager IT-Trainingslager

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, certificateRefs auf ein Secret im Namespace des Gateways.
  • cert-manager liest die Annotation cert-manager.io/cluster-issuer am 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 -enddate

Erwartet:

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 authority direkt nach der Installation? Der Webhook bekommt sein CA-Bundle erst nach einigen Sekunden. 30 s warten, dann kubectl apply wiederholen.

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-shop

Erwartet:

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 .service

Erwartet:

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: ClusterIssuer
kubectl 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=90s

Erwartet (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 -3

Erwartet:

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 -k und insecureSkipVerify gehören in kein Runbook. BackendTLSPolicy mit hostname prü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_seconds aus cert-manager plus ein externer Check (Tag 12).