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
tag16mit Default-Deny wie innotes. - Pro Fehlerbild: einbauen, Symptom ansehen, Ursache mit Werkzeugen nachweisen, beheben, nachmessen.
linkerd diagnosticsfragt 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=denyDie 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 -cErwartet (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/webErwartet:
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 deployErwartet (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 --proxywarnt hier (und innotes) 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 aufupin 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 wideErwartet (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 tapzeigt abgelehnte Requests nicht – sie enden vor der Stelle, an der tap mitliest. Für 403 sind Proxy-Log undviz authzdie 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 -cErwartet (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 opaqueErwartet (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-portsam Workload ersetzt die Standardliste (25, 587, 3306, …) für diesen Pod, statt sie zu ergänzen. Als Alternative am Service gehtappProtocol: linkerd.io/opaqueam 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-apiErwartet:
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-apiErwartet (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-initsteht 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=helperErwartet:
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 -4Erwartet (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=helperErwartet (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 helperErwartet (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-requestgrößer als das Limit, scheitert schon das Anlegen des Pods (FailedCreate, „must be less than or equal to memory limit“ – auch fürlinkerd-init).rollout statuswartet dann nur stumm; die Ursache steht inkubectl 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 checkmeldet es unterlinkerd-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
- Zeig, welche Pods in
tag16einen Proxy haben und welchen. Zeitziel: 20 s - Zeig, welcher Server und welche Regeln für Port 5432 in
postgres-0gelten. Zeitziel: 40 s - Zeig, welche Identitäten
notes-apibisher abgelehnt hat und wie oft. Zeitziel: 60 s - Zeig, wann der Issuer und das Proxy-Zertifikat von
webablaufen. 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 podsErwartet: alle Pods 2/2 Running.
kubectl -n tag16 logs deploy/last -c last --since=55s | awk '{print $2, $3}' \
| sort | uniq -cErwartet: /api/notes nur
200, /flaky fast nur 200 (Retries
aus Drill 6).
linkerd check --proxy -n tag16 2>&1 | tail -1Erwartet:
Status check results are √
kubectl -n tag16 get pods -o custom-columns=NAME:.metadata.name,\
PROXY-RESTARTS:.status.initContainerStatuses[1].restartCountErwartet: 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:80Erwartet (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 tag16Erwartet: 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, danndiagnostics policy/endpointsals 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 debugper RBAC begrenzen: Ein Debug-Container erbt die Identität des Pods und damit alle Rechte im Mesh.