Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 16: Fehlersuche

Ziel: Du findest die typischen Mesh-Fehler mit den Linkerd-Werkzeugen in wenigen Minuten und behebst sie, ohne zu raten. · Dauer: ca. 90 min · Voraussetzung: Tag 7

Briefing

  • Arbeite von außen nach innen: Lastgenerator, linkerd check, Metriken, Policy des Proxys, erst zuletzt Logs.
  • Heute baust du jeden Fehler selbst ein – in einer Kopie der App im Namespace tag16 mit Default-Deny wie in notes.
  • Pro Fehlerbild: einbauen, Symptom ansehen, Ursache mit Werkzeugen nachweisen, beheben, nachmessen.
  • linkerd diagnostics fragt den Proxy oder die Control Plane direkt und braucht kein Prometheus. Das hilft genau dann, wenn viz selbst blind ist.

Vorgehen

Symptom Erster Befehl Häufige Ursache
Pod 1/1 statt 2/2 linkerd check --proxy -n <ns> nicht neu gestartet
Alles 403 Proxy-Log grep 'Request denied' kein Server/keine Regel
Einzelner Client 403 linkerd viz edges -o wide falscher ServiceAccount
Genau 10 s Wartezeit linkerd diagnostics policy svc/<name> <port> Opaque Port fehlt
Init:Error, DB zu proxy-metrics auf port_skipped Skip-Port, alter Sidecar
Retry/Timeout wirkt nicht linkerd diagnostics policy svc/<name> <port> falscher parentRef
503 vom Client-Proxy linkerd diagnostics endpoints <fqdn>:<port> keine Endpunkte
Proxy startet neu kubectl get pod -o jsonpath=…lastState OOMKilled
Pod nicht Ready kubectl get events Route am Server (Tag 6)
TLS-Fehler, keine Identität linkerd check (Abschnitt identity) Issuer abgelaufen, Uhr

Drill 1: Annotiert, aber nicht im Mesh

Die Kopie der App: eine Replika pro Dienst, eigene ServiceAccounts, Postgres mit Volume. Der Namespace wird erst nach dem Deployment annotiert – wie so oft im Betrieb.

mkdir -p ~/linkerd/tag16 && cd ~/linkerd/tag16
kubectl create namespace tag16
for a in web notes-api helper last postgres; do
  kubectl -n tag16 create serviceaccount $a
done
cat > app.yaml <<'EOF'
apiVersion: v1
kind: Secret
metadata: {name: notes-db, namespace: tag16}
stringData:
  password: lab-db-123
  url: postgres://notes:lab-db-123@postgres:5432/notes?sslmode=disable
---
apiVersion: apps/v1
kind: StatefulSet
metadata: {name: postgres, namespace: tag16}
spec:
  serviceName: postgres
  replicas: 1
  selector: {matchLabels: {app: postgres}}
  template:
    metadata: {labels: {app: postgres}}
    spec:
      serviceAccountName: postgres
      containers:
      - name: postgres
        image: docker.io/library/postgres:18.7-alpine
        env:
        - {name: POSTGRES_USER, value: notes}
        - {name: POSTGRES_DB, value: notes}
        - name: POSTGRES_PASSWORD
          valueFrom: {secretKeyRef: {name: notes-db, key: password}}
        - {name: PGDATA, value: /var/lib/postgresql/data/pgdata}
        ports: [{containerPort: 5432, name: postgres}]
        readinessProbe:
          exec: {command: [pg_isready, -U, notes, -d, notes]}
        volumeMounts: [{name: data, mountPath: /var/lib/postgresql/data}]
  volumeClaimTemplates:
  - metadata: {name: data}
    spec:
      accessModes: [ReadWriteOnce]
      resources: {requests: {storage: 1Gi}}
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: tag16
  annotations: {config.linkerd.io/opaque-ports: "5432"}
spec:
  selector: {app: postgres}
  ports: [{port: 5432, targetPort: postgres, name: postgres}]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: notes-api, namespace: tag16}
spec:
  replicas: 1
  selector: {matchLabels: {app: notes-api}}
  template:
    metadata: {labels: {app: notes-api}}
    spec:
      serviceAccountName: notes-api
      initContainers:
      - name: migrate
        image: ghcr.io/thomaszachmann/notes-api:0.7.1
        args: [migrate]
        env:
        - name: NOTES_DB_URL
          valueFrom: {secretKeyRef: {name: notes-db, key: url}}
      containers:
      - name: notes-api
        image: ghcr.io/thomaszachmann/notes-api:0.7.1
        ports: [{containerPort: 8080, name: http}]
        env:
        - name: NOTES_DB_URL
          valueFrom: {secretKeyRef: {name: notes-db, key: url}}
        - {name: NOTES_API_KEY, value: lab-key-123}
        readinessProbe:
          httpGet: {path: /healthz, port: http}
---
apiVersion: v1
kind: Service
metadata: {name: notes-api, namespace: tag16}
spec:
  selector: {app: notes-api}
  ports: [{port: 80, targetPort: http, name: http}]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: helper, namespace: tag16}
spec:
  replicas: 1
  selector: {matchLabels: {app: helper}}
  template:
    metadata: {labels: {app: helper}}
    spec:
      serviceAccountName: helper
      containers:
      - name: helper
        image: ghcr.io/mccutchen/go-httpbin:2.26.0
        ports: [{containerPort: 8080, name: http}]
        readinessProbe:
          httpGet: {path: /status/200, port: http}
---
apiVersion: v1
kind: Service
metadata: {name: helper, namespace: tag16}
spec:
  selector: {app: helper}
  ports: [{port: 80, targetPort: http, name: http}]
---
apiVersion: v1
kind: ConfigMap
metadata: {name: web-conf, namespace: tag16}
data:
  default.conf: |
    server {
      listen 8080;
      location /api/ {
        proxy_set_header X-API-Key lab-key-123;
        proxy_pass http://notes-api.tag16.svc.cluster.local/;
      }
      location /flaky {
        proxy_pass http://helper.tag16.svc.cluster.local/unstable?failure_rate=0.3;
      }
    }
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: web, namespace: tag16}
spec:
  replicas: 1
  selector: {matchLabels: {app: web}}
  template:
    metadata: {labels: {app: web}}
    spec:
      serviceAccountName: web
      containers:
      - name: web
        image: docker.io/nginxinc/nginx-unprivileged:1.31.7-alpine
        ports: [{containerPort: 8080, name: http}]
        volumeMounts: [{name: conf, mountPath: /etc/nginx/conf.d}]
      volumes: [{name: conf, configMap: {name: web-conf}}]
---
apiVersion: v1
kind: Service
metadata: {name: web, namespace: tag16}
spec:
  selector: {app: web}
  ports: [{port: 80, targetPort: http, name: http}]
---
apiVersion: apps/v1
kind: Deployment
metadata: {name: last, namespace: tag16}
spec:
  replicas: 1
  selector: {matchLabels: {app: last}}
  template:
    metadata: {labels: {app: last}}
    spec:
      serviceAccountName: last
      containers:
      - name: last
        image: docker.io/curlimages/curl:8.23.0
        command: [sh, -c]
        args:
        - |
          while true; do
            for p in /api/notes /api/notes /flaky; do
              code=$(curl -s -o /dev/null -w '%{http_code}' -m 5 http://web$p)
              echo "$(date +%T) $p $code"
            done
            sleep 1
          done
EOF
kubectl apply -f app.yaml
kubectl -n tag16 rollout status statefulset/postgres --timeout=180s
kubectl -n tag16 rollout status deploy/notes-api --timeout=180s
kubectl annotate namespace tag16 linkerd.io/inject=enabled \
  config.linkerd.io/default-inbound-policy=deny

Die App läuft, last misst 100 Prozent für /api/notes. Aber ist sie im Mesh?

kubectl -n tag16 get pods -o custom-columns=NAME:.metadata.name,\
PROXY:.metadata.annotations.linkerd\\.io/proxy-version
linkerd viz stat -n tag16 deploy
linkerd check --proxy -n tag16 --wait 30s 2>&1 | grep -A2 'proxies are ready'

Erwartet (gekürzt):

NAME                        PROXY
helper-79d57fbbbb-mqhpg     <none>
last-78895758f9-52xd7       <none>
notes-api-5bc98b7fb-n4s5j   <none>
postgres-0                  <none>
web-7d94ccc84d-qjrst        <none>
No traffic found.
× data plane proxies are ready
    no "linkerd-proxy" containers found in the "tag16" namespace
    see https://linkerd.io/2/checks/#l5d-data-plane-ready for hints

Der Webhook greift nur beim Anlegen eines Pods (Tag 2). --wait 30s ist wichtig: Ohne wartet check --proxy bis zu fünf Minuten darauf, dass Proxys auftauchen. Die Lösung ist ein Neustart:

kubectl -n tag16 rollout restart deploy
kubectl -n tag16 rollout restart statefulset/postgres
kubectl -n tag16 rollout status statefulset/postgres --timeout=180s
sleep 45
kubectl -n tag16 get pods
kubectl -n tag16 logs deploy/last -c last --since=20s | awk '{print $2, $3}' \
  | sort | uniq -c

Erwartet (gekürzt):

NAME                         READY   STATUS       RESTARTS      AGE
helper-5c9445c87c-khfww      2/2     Running      0             53s
last-6ddfdfcc46-8cpmp        2/2     Running      0             53s
notes-api-5b6fbd4d9c-fd4n7   1/2     Init:Error   2 (38s ago)   52s
notes-api-5bc98b7fb-n4s5j    0/1     Running      0             2m3s
postgres-0                   2/2     Running      0             51s
web-6df978d4f-mhgj5          2/2     Running      0             52s
     30 /api/notes 403
     14 /flaky 403

Alles im Mesh – und alles kaputt. Das ist der nächste Fehler.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Default-Deny ohne Regeln

Mit dem Neustart gilt die Default-Policy deny aus der Namespace-Annotation. Was zeigt viz?

linkerd viz stat -n tag16 deploy
linkerd viz authz -n tag16 deploy/web

Erwartet:

NAME        MESHED   SUCCESS   RPS   LATENCY_P50   LATENCY_P95   LATENCY_P99   TCP_CONN
helper         1/1         -     -             -             -             -          -
last           1/1         -     -             -             -             -          -
notes-api      1/2         -     -             -             -             -          -
web            1/1         -     -             -             -             -          -
ROUTE  SERVER  AUTHORIZATION  UNAUTHORIZED  SUCCESS  RPS  LATENCY_P50  LATENCY_P95 ...

Nichts. viz liest Prometheus, und Prometheus wird auf Port 4191 selbst abgewiesen (Tag 6, Drill 6). Also direkt an den Proxy – über Log und diagnostics, die per Port-Forward über localhost kommen:

kubectl -n tag16 logs deploy/web -c linkerd-proxy --since=1m \
  | grep 'Request denied' | grep -v admin | tail -1 \
  | grep -oE 'server.name=[^ ]*|client.tls=[^ ]*'
P=$(kubectl -n tag16 get pod -l app=web -o name)
linkerd diagnostics policy -n tag16 $P 8080 -o json \
  | jq -c '{server: .labels.name, authz: .authorizations}'
linkerd diagnostics proxy-metrics -n tag16 po/postgres-0 \
  | grep '^inbound_tcp_authz_deny_total' \
  | grep -oE '(srv_name|client_id)="[^"]*"|\} [0-9]+' | paste - - -

Erwartet (gekürzt):

server.name=deny
client.tls=Some(Established
{"server":"deny","authz":null}
srv_name="deny"  client_id="notes-api.tag16.serviceaccount.identity.linkerd.cl...  } 7
srv_name="deny"  } 34

server.name=deny heißt: Kein Server passt, es gilt die Default-Policy, und die hat keine einzige Erlaubnis. Postgres lehnt deshalb auch migrate ab (Init:Error). Die Regeln aus Tag 6 passen eins zu eins, nur der Namespace ist ein anderer:

for f in servers authz admin; do
  sed 's/namespace: notes/namespace: tag16/' ~/linkerd/tag06/$f.yaml; echo ---
done > policy.yaml
grep -c '^kind:' policy.yaml
kubectl apply -f policy.yaml
kubectl -n tag16 rollout status deploy/notes-api --timeout=180s
sleep 60
kubectl -n tag16 logs deploy/last -c last --since=55s | awk '{print $2, $3}' \
  | sort | uniq -c
linkerd viz stat -n tag16 deploy

Erwartet (gekürzt, Zahlen schwanken):

14
...
deployment "notes-api" successfully rolled out
     80 /api/notes 200
      4 /api/notes 503
     29 /flaky 200
     12 /flaky 500
NAME        MESHED   SUCCESS      RPS   LATENCY_P50   LATENCY_P95   LATENCY_P99 ...
helper         1/1    80.88%   1.1rps           1ms          14ms          19ms
last           1/1   100.00%   0.3rps           1ms          49ms          50ms
notes-api      1/1   100.00%   1.7rps           7ms          35ms          39ms
web            1/1    87.42%   2.5rps          16ms          69ms          94ms

Die vier 503 fallen in die Sekunden, bis migrate im Backoff wieder anläuft: Ohne bereiten Pod antwortet der Proxy von web nach drei Sekunden selbst mit 503. Ab jetzt ist tag16 gesund – die Baseline für die nächsten Fehler.

Achtung: linkerd viz check --proxy warnt hier (und in notes) mit „prometheus is authorized to scrape data plane pods“. Die Prüfung sucht eine Regel für das viz-eigene Prometheus. Mit der NetworkAuthentication aus Tag 6 ist das ein Fehlalarm – verlass dich auf up in Prometheus.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Der falsche ServiceAccount

Ein Kollege spielt last neu ein und vergisst serviceAccountName:

kubectl -n tag16 set serviceaccount deploy/last default
kubectl -n tag16 rollout status deploy/last --timeout=120s
sleep 60
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c
linkerd viz authz -n tag16 deploy/web | grep web-http
linkerd viz edges -n tag16 deploy -o wide

Erwartet (gekürzt):

     62 /api/notes 403
     30 /flaky 403
default  web-http                                    2.3rps    0.00%  0.0rps ...
default  web-http  authorizationpolicy/web-von-last  0.0rps   89.71%  1.1rps ...
SRC    DST   SRC_NS   DST_NS   CLIENT_ID       SERVER_ID   SECURED
last   web   tag16    tag16    default.tag16   web.tag16   √

Die Zeile ohne Regel mit 2,3 rps in UNAUTHORIZED ist der Treffer, edges -o wide nennt die Identität: default.tag16. Die Regel erwartet aber last:

kubectl -n tag16 logs deploy/web -c linkerd-proxy --since=1m \
  | grep -m1 'Request denied' | grep -oE 'server.name=[^ ]*|Name\("[^"]*'
kubectl -n tag16 get meshtlsauthentication last -o jsonpath='{.spec}{"\n"}'

Erwartet:

server.name=web-http
Name("default.tag16.serviceaccount.identity.linkerd.cluster.local
{"identityRefs":[{"kind":"ServiceAccount","name":"last"}]}

Tipp: linkerd viz tap zeigt abgelehnte Requests nicht – sie enden vor der Stelle, an der tap mitliest. Für 403 sind Proxy-Log und viz authz die Werkzeuge.

Mit welcher Identität ein Pod spricht, prüfst du auch ohne Shell im Image: Ein Ephemeral Container teilt Netz und Proxy des Pods. Aus helper heraus, der notes-api nicht aufrufen darf:

P=$(kubectl -n tag16 get pod -l app=helper -o jsonpath='{.items[0].metadata.name}')
kubectl -n tag16 debug $P -q --image=docker.io/curlimages/curl:8.23.0 -c probe -- \
  curl -s -o /dev/null -w '%{http_code}\n' -H 'X-API-Key: lab-key-123' \
  http://notes-api/notes
sleep 5
kubectl -n tag16 logs $P -c probe
kubectl -n tag16 logs deploy/notes-api -c linkerd-proxy --since=1m \
  | grep 'Request denied' | tail -1 | grep -oE 'Name\("[^"]*'

Erwartet:

403
Name("helper.tag16.serviceaccount.identity.linkerd.cluster.local

Der Debug-Container hat die Identität des Pods – praktisch, um eine Regel aus Sicht genau dieses Clients zu testen. Jetzt last reparieren:

kubectl -n tag16 set serviceaccount deploy/last last
kubectl -n tag16 rollout status deploy/last --timeout=120s
sleep 45
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c

Erwartet (Zahlen schwanken):

     54 /api/notes 200
     21 /flaky 200
      6 /flaky 500

Dasselbe Bild entsteht, wenn in der MeshTLSAuthentication ein Tippfehler steckt oder der ServiceAccount aus einem anderen Namespace kommt (identityRefs mit namespace).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Zehn Sekunden Stille

Ein Dienst, bei dem der Server zuerst spricht – wie SMTP oder MySQL. Er meldet sich mit einer Begrüßungszeile auf Port 2525, der nicht in Linkerds Opaque-Liste steht:

kubectl -n tag16 create serviceaccount banner
cat > banner.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata: {name: banner, namespace: tag16}
spec:
  replicas: 1
  selector: {matchLabels: {app: banner}}
  template:
    metadata: {labels: {app: banner}}
    spec:
      serviceAccountName: banner
      containers:
      - name: banner
        image: docker.io/library/busybox:1.37
        command: [nc, -lk, -p, "2525", -e, echo, "220 banner bereit"]
        ports: [{containerPort: 2525, name: smtp}]
---
apiVersion: v1
kind: Service
metadata: {name: banner, namespace: tag16}
spec:
  selector: {app: banner}
  ports: [{port: 2525, targetPort: smtp, name: smtp}]
---
apiVersion: policy.linkerd.io/v1beta3
kind: Server
metadata: {name: banner, namespace: tag16}
spec:
  podSelector: {matchLabels: {app: banner}}
  port: smtp
---
apiVersion: policy.linkerd.io/v1alpha1
kind: AuthorizationPolicy
metadata: {name: banner-von-last, namespace: tag16}
spec:
  targetRef: {group: policy.linkerd.io, kind: Server, name: banner}
  requiredAuthenticationRefs:
  - {group: policy.linkerd.io, kind: MeshTLSAuthentication, name: last}
EOF
kubectl apply -f banner.yaml
kubectl -n tag16 rollout status deploy/banner --timeout=120s
kubectl -n tag16 exec deploy/last -c last -- sh -c 's=$(date +%s); (sleep 15) \
  | nc banner 2525 | while read l; do echo "$(( $(date +%s) - s )) s: $l"; done'

Erwartet:

10 s: 220 banner bereit

Exakt zehn Sekunden. Der Client-Proxy wartet auf die ersten Bytes des Clients, um das Protokoll zu erkennen. Der Client wartet auf den Server. Beide warten, bis der Proxy aufgibt:

kubectl -n tag16 logs deploy/last -c linkerd-proxy --since=1m | grep 'after timeout'
linkerd diagnostics policy -n tag16 svc/banner 2525 -o json \
  | jq -c '.protocol.Kind | keys, .Detect.timeout'

Erwartet (gekürzt):

INFO ThreadId(01) outbound:proxy{addr=10.99.111.91:2525}: linkerd_app_outbound::pro...
  ...tocol: Continuing after timeout: 10s
["Detect"]
{"seconds":10}

diagnostics policy mit einem Service zeigt die Outbound-Sicht: Protokoll Detect mit zehn Sekunden Frist. Also Opaque Port, am Service:

kubectl -n tag16 annotate service banner config.linkerd.io/opaque-ports=2525
sleep 5
linkerd diagnostics policy -n tag16 svc/banner 2525 -o json \
  | jq -c '.protocol.Kind | keys'
kubectl -n tag16 exec deploy/last -c last -- sh -c 's=$(date +%s); (sleep 3) \
  | nc banner 2525 | while read l; do echo "$(( $(date +%s) - s )) s: $l"; done'
linkerd check --proxy -n tag16 --wait 30s 2>&1 | grep -A2 opaque

Erwartet (gekürzt):

["Opaque"]
0 s: 220 banner bereit
‼ opaque ports are properly annotated
    * service banner expects target port 2525 to be opaque; add it to pod
      banner-84d6cdb7b8-pl2kb config.linkerd.io/opaque-ports annotation

Für Clients im Mesh reicht der Service. check will die Annotation auch am Pod – für direkte Pod-Aufrufe und Headless Services:

kubectl -n tag16 patch deploy banner -p '{"spec":{"template":{"metadata":
  {"annotations":{"config.linkerd.io/opaque-ports":"2525"}}}}}'
kubectl -n tag16 rollout status deploy/banner --timeout=120s
linkerd check --proxy -n tag16 --wait 30s 2>&1 | grep -E 'opaque|Status check'

Erwartet:

√ opaque ports are properly annotated
Status check results are √

Achtung: Die Annotation config.linkerd.io/opaque-ports am Workload ersetzt die Standardliste (25, 587, 3306, …) für diesen Pod, statt sie zu ergänzen. Als Alternative am Service geht appProtocol: linkerd.io/opaque am Port.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Am Proxy vorbei

Jemand wollte die Datenbankverbindung „schneller“ machen und nimmt Port 5432 aus dem Proxy heraus:

kubectl -n tag16 patch deploy notes-api -p '{"spec":{"template":{"metadata":
  {"annotations":{"config.linkerd.io/skip-outbound-ports":"5432"}}}}}'
sleep 50
kubectl -n tag16 get pods -l app=notes-api

Erwartet:

NAME                         READY   STATUS       RESTARTS      AGE
notes-api-5b6fbd4d9c-fd4n7   2/2     Running      0             9m37s
notes-api-794d4966dd-bzmxp   1/2     Init:Error   2 (42s ago)   50s

Der alte Pod läuft weiter, die Nutzer merken nichts – der Rollout hängt. Wer lehnt ab?

P=$(kubectl -n tag16 get pod -l app=notes-api \
  --sort-by=.metadata.creationTimestamp -o name | tail -1)
kubectl -n tag16 logs $P -c migrate --tail=1
linkerd diagnostics proxy-metrics -n tag16 po/postgres-0 \
  | grep '^inbound_tcp_authz_deny_total' \
  | grep -oE '(srv_name|no_tls_reason)="[^"]*"|\} [0-9]+' | paste - - -
kubectl -n tag16 get $P -o jsonpath='{.spec.initContainers[0].args}' \
  | grep -o '"--outbound-ports-to-ignore","[^"]*"'

Erwartet (gekürzt):

time=2026-11-19T20:05:56.868Z level=ERROR msg="database unreachable" source=env
err="failed to connect to `user=notes database=notes`: 10.100.223.86:5432 (postgres):
failed to receive message: unexpected EOF"
srv_name="postgres"  no_tls_reason="port_skipped"  } 16
"--outbound-ports-to-ignore","5432"

port_skipped heißt: Klartext auf einem Opaque Port. linkerd-init hat 5432 an den iptables-Regeln vorbeigeleitet, notes-api spricht ohne Proxy und ohne Identität. Zurück:

kubectl -n tag16 patch deploy notes-api --type=json -p '[{"op":"remove",
  "path":"/spec/template/metadata/annotations/config.linkerd.io~1skip-outbound-ports"}]'
kubectl -n tag16 rollout status deploy/notes-api --timeout=180s
kubectl -n tag16 get pods -l app=notes-api

Erwartet (gekürzt):

deployment "notes-api" successfully rolled out
NAME                         READY   STATUS        RESTARTS      AGE
notes-api-5b6fbd4d9c-fd4n7   2/2     Running       0             9m48s
notes-api-794d4966dd-bzmxp   1/2     Terminating   3 (38s ago)   61s

Genau dasselbe Bild – Init:Error, port_skipped – liefert ein Init-Container ohne nativen Sidecar (Tag 6, Drill 7). Erkennungsmerkmal dort: die Annotation config.beta.linkerd.io/proxy-enable-native-sidecar: "false" und linkerd-init hinter deinem Init-Container in spec.initContainers.

Tipp: In den Argumenten von linkerd-init steht auch die Voreinstellung --inbound-ports-to-ignore 4190,4191,4567,4568. Eingehend auf 4567/4568 (Galera) nimmt Linkerd also schon von sich aus nichts an.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Die Route, die nichts tut

Retries für helper wie an Tag 7 – mit einem kleinen Fehler im parentRef:

cat > route-retry.yaml <<'EOF'
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: helper-retry
  namespace: tag16
  annotations:
    retry.linkerd.io/http: 5xx
    retry.linkerd.io/limit: "2"
spec:
  parentRefs:
  - {group: core, kind: Service, name: helper, port: 8080}
  rules:
  - matches:
    - path: {type: PathPrefix, value: /}
      method: GET
EOF
kubectl apply -f route-retry.yaml
sleep 65
kubectl -n tag16 logs deploy/last -c last --since=60s | awk '{print $2, $3}' \
  | sort | uniq -c
kubectl -n tag16 get httproute helper-retry \
  -o jsonpath='{.status.parents[0].conditions[*].reason}{"\n"}'

Erwartet (Zahlen schwanken):

     92 /api/notes 200
     33 /flaky 200
     13 /flaky 500
Accepted ResolvedRefs

Weiter 70 Prozent, obwohl die Route Accepted ist. Der Policy-Controller prüft nicht, ob der Service den Port 8080 überhaupt hat. Was der Proxy wirklich bekommt:

linkerd diagnostics policy -n tag16 svc/helper 80 -o json \
  | jq -c '.protocol.Kind.Detect.http1.routes[].metadata.Kind'
linkerd diagnostics policy -n tag16 svc/helper 8080 -o json \
  | jq -c '.protocol.Kind.Detect.http1.routes[].metadata.Kind'
linkerd diagnostics proxy-metrics -n tag16 deploy/web \
  | grep -c '^outbound_http_route_retry_requests_total'

Erwartet:

{"Default":"http"}
{"Resource":{"group":"gateway.networking.k8s.io","kind":"HTTPRoute","name":"helper-r...
0

parentRef.port ist der Service-Port (80), nicht der Container-Port (8080). Auf Port 80 sieht der Proxy nur die Standardroute, null Retries.

sed -i 's/port: 8080}/port: 80}/' route-retry.yaml
kubectl apply -f route-retry.yaml
sleep 65
kubectl -n tag16 logs deploy/last -c last --since=60s | awk '{print $2, $3}' \
  | sort | uniq -c
linkerd diagnostics proxy-metrics -n tag16 deploy/web \
  | grep '^outbound_http_route_retry_requests_total' \
  | grep -oE 'route_name="[^"]*"|[0-9]+$' | paste - -

Erwartet (Zahlen schwanken):

     84 /api/notes 200
     40 /flaky 200
      2 /flaky 500
route_name="helper-retry"  14

Weitere Kandidaten, wenn eine Route nichts tut: group vergessen (ohne Angabe gilt gateway.networking.k8s.io), Route in einem anderen Namespace als der Service, ein ServiceProfile für denselben Service (es gewinnt, Tag 7) oder ein Client ohne Proxy – Retries macht nur der Client-Proxy. Ein Retry-Budget wie früher im ServiceProfile gibt es an HTTPRoutes nicht, nur limit.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Ein umbenannter Port

Ein Entwickler benennt in helper den Container-Port von http in web um und zieht die Probe mit:

kubectl -n tag16 patch deploy helper --type=json -p '[
  {"op":"replace","path":"/spec/template/spec/containers/0/ports/0/name",
   "value":"web"},
  {"op":"replace",
   "path":"/spec/template/spec/containers/0/readinessProbe/httpGet/port",
   "value":"web"}]'
kubectl -n tag16 rollout status deploy/helper --timeout=120s
sleep 50
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c
linkerd diagnostics endpoints helper.tag16.svc.cluster.local:80
kubectl -n tag16 get endpointslices -l kubernetes.io/service-name=helper

Erwartet:

     58 /api/notes 200
     29 /flaky 503
No endpoints found.
NAME           ADDRESSTYPE   PORTS     ENDPOINTS    AGE
helper-jcdjm   IPv4          <unset>   10.0.1.106   60s

Der Pod ist bereit, aber der Service sucht targetPort: http – den gibt es nicht mehr. diagnostics endpoints zeigt, was linkerd-destination an die Proxys verteilt: nichts. Für mehr Details im Proxy von web hebst du den Log-Level an. Die Annotation wirkt erst nach einem Neustart und erzeugt viel Text – nur kurz einsetzen:

kubectl -n tag16 patch deploy web -p '{"spec":{"template":{"metadata":
  {"annotations":{"config.linkerd.io/proxy-log-level":"warn,linkerd=debug"}}}}}'
kubectl -n tag16 rollout status deploy/web --timeout=120s
sleep 30
kubectl -n tag16 logs deploy/web -c linkerd-proxy --since=30s \
  | grep -oE 'name=helper port=80\}:pool: .*' | cut -c1-80 | sort | uniq -c \
  | sort -rn | head -4

Erwartet (gekürzt):

     21 name=helper port=80}:pool: linkerd_pool_p2c: No ready endpoints
      7 name=helper port=80}:pool: linkerd_proxy_api_resolve::resolve: Resolving ds
      6 name=helper port=80}:pool: linkerd_proxy_resolve::recover: recovering err=c
      1 name=helper port=80}:pool: linkerd_proxy_balance_queue::worker: Unavailable

„No ready endpoints“, dann Fail-Fast nach drei Sekunden: daher die 503. Die naheliegende Reparatur ist, den Service nachzuziehen:

kubectl -n tag16 patch service helper --type=json \
  -p '[{"op":"replace","path":"/spec/ports/0/targetPort","value":"web"}]'
sleep 20
linkerd diagnostics endpoints helper.tag16.svc.cluster.local:80
kubectl -n tag16 logs deploy/last -c last --since=12s | awk '{print $2, $3}' \
  | sort | uniq -c
P=$(kubectl -n tag16 get pod -l app=helper -o name)
linkerd diagnostics policy -n tag16 $P 8080 -o json | jq -c '{server: .labels.name}'

Erwartet:

NAMESPACE   IP           PORT   POD                      SERVICE
tag16       10.0.1.106   8080   helper-9d8c45bb8-gsbm5   helper.tag16
     18 /api/notes 200
      9 /flaky 403
{"server":"deny"}

Endpunkte da, jetzt 403: Auch der Server helper-http sucht port: http. Der Port fällt unter die Default-Policy. Port-Namen sind ein Vertrag zwischen Pod, Service und Server. Richtig ist, den Namen zurückzudrehen – und den Log-Level gleich mit:

kubectl -n tag16 patch deploy helper --type=json -p '[
  {"op":"replace","path":"/spec/template/spec/containers/0/ports/0/name",
   "value":"http"},
  {"op":"replace",
   "path":"/spec/template/spec/containers/0/readinessProbe/httpGet/port",
   "value":"http"}]'
kubectl -n tag16 patch service helper --type=json \
  -p '[{"op":"replace","path":"/spec/ports/0/targetPort","value":"http"}]'
kubectl -n tag16 patch deploy web --type=json -p '[{"op":"remove",
  "path":"/spec/template/metadata/annotations/config.linkerd.io~1proxy-log-level"}]'
kubectl -n tag16 rollout status deploy/helper --timeout=120s
kubectl -n tag16 rollout status deploy/web --timeout=120s
sleep 50
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c
P=$(kubectl -n tag16 get pod -l app=helper -o name)
linkerd diagnostics policy -n tag16 $P 8080 -o json | jq -c '{server: .labels.name}'

Erwartet (Zahlen schwanken):

     59 /api/notes 200
     28 /flaky 200
      1 /flaky 500
{"server":"helper-http"}

Fortschritt speichern? Kostenlos registrieren

Drill 8: Proxy OOMKilled

Ressourcen für den Proxy setzt du per Annotation. Ein zu knappes Limit fällt im Leerlauf nicht auf – der Proxy braucht hier nur rund 3 MiB:

kubectl top pod -n tag16 --containers | grep -E 'POD|helper.*proxy'
kubectl -n tag16 patch deploy helper -p '{"spec":{"template":{"metadata":
  {"annotations":{"config.linkerd.io/proxy-memory-limit":"6Mi"}}}}}'
kubectl -n tag16 rollout status deploy/helper --timeout=120s
kubectl -n tag16 get pods -l app=helper

Erwartet (gekürzt):

POD                          NAME            CPU(cores)   MEMORY(bytes)
helper-5c9445c87c-khfww      linkerd-proxy   4m           3Mi
NAME                      READY   STATUS    RESTARTS   AGE
helper-665b47786f-lt26b   2/2     Running   0          45s

Läuft. Dann kommt Last: 200 gleichzeitige, langsame Requests aus web (go-httpbin /drip tröpfelt die Antwort über fünf Sekunden):

kubectl -n tag16 exec deploy/web -c web -- sh -c 'seq 400 | xargs -P 200 -I{} \
  curl -s -o /dev/null -w "%{http_code}\n" -m 20 \
  "http://helper/drip?duration=5&numbytes=5&delay=0"' | sort | uniq -c
kubectl -n tag16 get pods -l app=helper
kubectl -n tag16 get pod -l app=helper -o custom-columns=NAME:.metadata.name,\
PROXY-RESTARTS:.status.initContainerStatuses[1].restartCount,\
GRUND:.status.initContainerStatuses[1].lastState.terminated.reason
kubectl -n tag16 get pod -l app=helper \
  -o jsonpath='{.items[0].spec.initContainers[1].resources}{"\n"}'

Erwartet (gekürzt, Zahlen schwanken):

command terminated with exit code 123
    199 200
    201 503
NAME                      READY   STATUS    RESTARTS      AGE
helper-665b47786f-5hwgq   2/2     Running   1 (11s ago)   30s
NAME                      PROXY-RESTARTS   GRUND
helper-665b47786f-5hwgq   1                OOMKilled
{"limits":{"memory":"6Mi"},"requests":{"memory":"6Mi"}}

Exit-Code 123 meldet nur xargs, weil einzelne curl scheiterten. Der Proxy ist ein Init-Container mit Dauerbetrieb, deshalb steht der Grund unter initContainerStatuses. Erwischst du den Pod im Backoff, heißt sein Status Init:CrashLoopBackOff. Während der Proxy neu startet, ist helper weg: 503 vom Proxy in web. Danach läuft der Pod wieder an – bis zur nächsten Lastspitze. Ohne request-Annotation setzt Kubernetes den Request gleich dem Limit. Limits gehören nach Messung unter Last gesetzt, mit Luft:

kubectl -n tag16 patch deploy helper -p '{"spec":{"template":{"metadata":
  {"annotations":{"config.linkerd.io/proxy-memory-limit":"128Mi",
  "config.linkerd.io/proxy-memory-request":"20Mi"}}}}}'
kubectl -n tag16 rollout status deploy/helper --timeout=120s
kubectl -n tag16 exec deploy/web -c web -- sh -c 'seq 400 | xargs -P 200 -I{} \
  curl -s -o /dev/null -w "%{http_code}\n" -m 20 \
  "http://helper/drip?duration=5&numbytes=5&delay=0"' | sort | uniq -c
kubectl -n tag16 get pods -l app=helper
kubectl top pod -n tag16 --containers | grep helper

Erwartet (gekürzt):

    400 200
NAME                      READY   STATUS    RESTARTS   AGE
helper-5bf6f997c8-zdqlt   2/2     Running   0          26s
helper-5bf6f997c8-zdqlt      helper          58m          9Mi
helper-5bf6f997c8-zdqlt      linkerd-proxy   63m          7Mi

Der Speicher des Proxys wächst mit gleichzeitigen Verbindungen und Requests, nicht mit der Zahl der Pods im Cluster.

Tipp: Ist die proxy-memory-request größer als das Limit, scheitert schon das Anlegen des Pods (FailedCreate, „must be less than or equal to memory limit“ – auch für linkerd-init). rollout status wartet dann nur stumm; die Ursache steht in kubectl get events.

Achtung: Zertifikats- und Uhrzeitfehler baust du besser nicht nach – sie treffen das ganze Mesh. Läuft der Issuer ab, bekommen neue Proxys keine Identität mehr (linkerd check meldet es unter linkerd-identity, das Proxy-Log zeigt Fehler beim Zertifikatsabruf, Pods werden nicht Ready). Geht die Uhr eines Nodes falsch, sind Zertifikate dort „noch nicht“ oder „nicht mehr“ gültig: mTLS-Handshakes scheitern nur von und zu Pods auf diesem Node. Frühwarnung: control_identity_cert_refreshes_total{result="error"} (Tag 3), Ablaufdaten von Issuer und Anchor (Tag 5) und NTP auf allen Nodes.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeig, welche Pods in tag16 einen Proxy haben und welchen. Zeitziel: 20 s
  2. Zeig, welcher Server und welche Regeln für Port 5432 in postgres-0 gelten. Zeitziel: 40 s
  3. Zeig, welche Identitäten notes-api bisher abgelehnt hat und wie oft. Zeitziel: 60 s
  4. Zeig, wann der Issuer und das Proxy-Zertifikat von web ablaufen. Zeitziel: 40 s

Lösung

kubectl -n tag16 get pods -o custom-columns=NAME:.metadata.name,\
PROXY:.metadata.annotations.linkerd\\.io/proxy-version
linkerd diagnostics policy -n tag16 po/postgres-0 5432 -o json \
  | jq -c '{server: .labels.name, authz: [.authorizations[].labels.name]}'
linkerd diagnostics proxy-metrics -n tag16 deploy/notes-api \
  | grep '^inbound_http_authz_deny_total' \
  | sed -E 's/.*client_id="([^"]*)".*\} /\1 /; s/^inbound.*\} /ohne-identitaet /'
kubectl -n linkerd get certificate linkerd-identity-issuer \
  -o jsonpath='{.status.notAfter}{"\n"}'
linkerd identity -n tag16 -l app=web | grep 'Not After'

Erwartet (gekürzt):

NAME                         PROXY
banner-f67576cf9-6kptm       edge-26.11.2
...
{"server":"postgres","authz":["postgres-von-notes-api"]}
helper.tag16.serviceaccount.identity.linkerd.cluster.local 1
ohne-identitaet 6
2026-11-21T16:02:00Z
            Not After : Nov 20 20:19:15 2026 UTC

ohne-identitaet sind die Prometheus-Scrapes auf 4191 aus Drill 2, bevor proxy-admin stand. Der Issuer gilt 48 Stunden und wird von cert-manager erneuert (Tag 5).

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl -n tag16 get pods

Erwartet: alle Pods 2/2 Running.

kubectl -n tag16 logs deploy/last -c last --since=55s | awk '{print $2, $3}' \
  | sort | uniq -c

Erwartet: /api/notes nur 200, /flaky fast nur 200 (Retries aus Drill 6).

linkerd check --proxy -n tag16 2>&1 | tail -1

Erwartet:

Status check results are √
kubectl -n tag16 get pods -o custom-columns=NAME:.metadata.name,\
PROXY-RESTARTS:.status.initContainerStatuses[1].restartCount

Erwartet: hinter jedem Pod eine 0 – kein Proxy-Neustart seit dem letzten Rollout.

Challenge

Spiel ein „Release“ ein, das zwei Dinge gleichzeitig ändert, und repariere danach alles, nur mit Linkerd-Werkzeugen und ohne die Befehle unten noch einmal anzusehen:

kubectl -n tag16 create serviceaccount web-v2
kubectl -n tag16 set serviceaccount deploy/web web-v2
kubectl -n tag16 patch service helper -p '{"spec":{"selector":{"app":"helper-v2"}}}'

web soll dabei web-v2 behalten.

Hinweis: Zwei Pfade, zwei verschiedene Statuscodes – zwei Ursachen.

Lösung

sleep 50
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c
kubectl -n tag16 logs deploy/notes-api -c linkerd-proxy --since=1m \
  | grep -m1 'Request denied' | grep -oE 'server.name=[^ ]*|Name\("[^"]*'
linkerd diagnostics endpoints helper.tag16.svc.cluster.local:80
kubectl -n tag16 get service helper -o jsonpath='{.spec.selector}{"\n"}'

Erwartet:

     59 /api/notes 403
     29 /flaky 503
server.name=notes-api-http
Name("web-v2.tag16.serviceaccount.identity.linkerd.cluster.local
No endpoints found.
{"app":"helper-v2"}

403 auf /api/notes: notes-api sieht die neue Identität web-v2, die Regel kennt nur web. 503 auf /flaky: Der Service findet keinen Pod. Die MeshTLSAuthentication web wird von zwei Regeln genutzt (notes-api-von-web, helper-von-web) – eine Änderung reicht für beide:

kubectl -n tag16 patch meshtlsauthentication web --type=merge -p '{"spec":
  {"identityRefs":[{"kind":"ServiceAccount","name":"web"},
  {"kind":"ServiceAccount","name":"web-v2"}]}}'
kubectl -n tag16 patch service helper -p '{"spec":{"selector":{"app":"helper"}}}'
sleep 50
kubectl -n tag16 logs deploy/last -c last --since=40s | awk '{print $2, $3}' \
  | sort | uniq -c
linkerd diagnostics endpoints helper.tag16.svc.cluster.local:80

Erwartet (Zahlen schwanken):

     48 /api/notes 200
     22 /flaky 200
      1 /flaky 500
NAMESPACE   IP           PORT   POD                       SERVICE
tag16       10.0.1.175   8080   helper-5bf6f997c8-l4fkh   helper.tag16

Hättest du nur die 403 gesucht, wäre /flaky mit 503 geblieben – und umgekehrt. Bei mehreren Symptomen jedes einzeln bis zur Ursache verfolgen.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

kubectl delete namespace tag16
kubectl get endpointslices -A | grep cilium-gateway | grep tag16

Erwartet: keine Ausgabe. Mit dem Namespace verschwinden auch PVC und die EndpointSlice cilium-gateway-helper, die Cilium zur Route aus Drill 6 angelegt hat.

Interview-Notiz

  • Wie gehst du bei einer Mesh-Störung vor? Von außen nach innen: Symptom messen, linkerd check --proxy, viz-Metriken, dann diagnostics policy/endpoints als Sicht des Proxys, zuletzt Logs mit erhöhtem Log-Level.
  • 403 oder 503 – wo suchst du? 403 ist Policy auf der Serverseite (Server, Identität, Route). 503 vom Proxy heißt meist: keine bereiten Endpunkte, Fail-Fast im Client-Proxy.
  • Warum hängt eine Verbindung genau zehn Sekunden? Protokollerkennung bei einem Protokoll, in dem der Server zuerst spricht – Opaque Port setzen.

Enterprise-Notiz

  • Runbooks pro Symptom wie die Tabelle oben, mit den exakten Befehlen. In der Störung liest niemand die Doku.
  • Alarme auf inbound_http_authz_deny_total, inbound_tcp_authz_deny_total, Proxy-Neustarts (kube_pod_init_container_status_restarts_total) und Retry-Quoten.
  • Debug-Log nie dauerhaft: Er kostet CPU, Speicher und Log-Volumen. Annotation per Change setzen und wieder entfernen.
  • Port-Namen, ServiceAccounts und Opaque-Ports per Admission-Policy (Kyverno, Gatekeeper) prüfen – die meisten Fehler von heute fängt man vor dem Deployment.
  • kubectl debug per RBAC begrenzen: Ein Debug-Container erbt die Identität des Pods und damit alle Rechte im Mesh.