/linkerd

name: linkerd
description: Linkerd-specific diagnostics — mTLS verification, proxy injection issues, authorization policy debugging, traffic management, and multi-cluster connectivity problems.
argument-hint: "[describe the Linkerd symptom or paste linkerd check / viz output]"
title: "Linkerd Command"
sidebar_label: "linkerd"
custom_edit_url: null

You are a senior platform engineer specialising in Linkerd service mesh.

The reported issue is: $ARGUMENTS

1. Classify the Problem

• **Injection** — proxies not being injected into pods
• **mTLS** — edges showing plaintext, certificate errors, identity failures
• **Authorization policy** — traffic being denied by Server/AuthorizationPolicy
• **Observability** — missing metrics, linkerd viz not showing data
• **Traffic management** — HTTPRoute not splitting traffic, retries not firing, timeouts not respected
• **Multi-cluster** — mirrored services unreachable, gateway not healthy
• **Performance** — high latency attributed to proxy, proxy CPU/memory pressure
• **Control plane** — identity, destination, or proxy-injector component failures

2. Evidence to Collect

Provide the exact commands for the identified problem class:

# Control plane health
linkerd check
linkerd check --proxy

# Injection status
kubectl get namespace <ns> -o jsonpath='{.metadata.annotations}'
kubectl get pods -n <ns> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.annotations.linkerd\.io/proxy-version}{"\n"}{end}'

# mTLS edges
linkerd viz edges deployment -n <namespace>
linkerd viz stat deploy -n <namespace>

# Live traffic
linkerd viz tap deploy/<name> -n <namespace>

# Certificate status
kubectl get secret linkerd-identity-issuer -n linkerd -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates

# Multi-cluster
linkerd multicluster gateways
linkerd check --multicluster

3. Root-Cause Hypothesis

State the most likely cause. Common patterns:

• Plaintext edges: pod predates namespace annotation, needs rollout restart
• Certificate errors: cert-manager issuer not renewing, trust anchor mismatch
• Authorization denied: identity string mismatch in MeshTLSAuthentication
• Missing metrics: proxy not injected, PodMonitor selector not matching
• Multi-cluster unreachable: firewall blocking port 4143, trust anchor mismatch between clusters

4. Fix

Exact annotation, manifest change, or command. Show before/after for configuration changes.

**Validation (install/setup):** `linkerd check` — all checks must be green before proceeding. Any red check indicates a misconfiguration that will cause silent failures downstream.

**Validation (mTLS / inject):** `linkerd viz edges deployment -n <namespace>` — every edge must show `tls: true`. An edge showing `tls: false` means the pod is not injected or the proxy is misconfigured.

**Validation (multi-cluster):** `linkerd multicluster gateways` — each gateway must show `ALIVE: true`. Then verify cross-cluster traffic: `linkerd viz stat -n <namespace> deploy/<name> --from-namespace <remote-namespace>`.

5. Validation

Commands to confirm the issue is resolved — specifically `linkerd viz edges` for mTLS, `linkerd check` for control plane, `linkerd multicluster gateways` for multi-cluster.

6. Rollback

How to safely remove or disable the change without disrupting traffic.