# linkerd check: Gate CI on Mesh Health

> linkerd check runs extensive health checks against a Linkerd install and control plane. Reference for --pre, --proxy, and the failed-check output that gates CI.

Source: https://latchkey.dev/learn/command-reference/linkerd-check  
Updated: 2026-06-30

linkerd check runs a battery of validations against your cluster and Linkerd install and exits non-zero if any check fails.

linkerd check is the canonical Linkerd CI gate. Run --pre before install and the full check after, and fail the job on the first red x.

## What it does

linkerd check validates the whole Linkerd stack: cluster prerequisites, control-plane pods and config, certificate validity and expiry, proxy versions, and data-plane readiness. Each check prints with a green checkmark or a red x plus a hint, and the command exits non-zero if any fail.

## Common usage

```Terminal
# preflight checks before installing
linkerd check --pre
# full control-plane and data-plane check
linkerd check
# only the proxies in a namespace
linkerd check --proxy -n my-app
```

## Options

| Flag | What it does |
| --- | --- |
| --pre | Run pre-install cluster checks only |
| --proxy | Check the data-plane proxies |
| -n, --namespace <ns> | Namespace to check proxies in (with --proxy) |
| --output json | JSON output for CI parsing |
| --wait <dur> | Wait up to this long for checks to pass |

## In CI

Run linkerd check --pre before linkerd install so an unsupported cluster fails early, then run linkerd check after install as a deploy gate. The certificate checks are especially valuable: they catch trust anchors nearing expiry before they take the mesh down.

## Common errors in CI

A failing line looks like "x control plane pods are ready" with a hint below, or "√ ... [FAIL]". "certificate will expire ... in Xh" flags an expiring trust anchor. "linkerd-config ... not found" means the control plane is not installed. "control plane version ... proxy version ... mismatch" warns a data-plane upgrade is pending. A non-zero exit is the signal to stop the pipeline.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### linkerd check: Gate CI on Mesh Health?

linkerd check is the canonical Linkerd CI gate. Run --pre before install and the full check after, and fail the job on the first red x.

### What it does?

linkerd check validates the whole Linkerd stack: cluster prerequisites, control-plane pods and config, certificate validity and expiry, proxy versions, and data-plane readiness. Each check prints with a green checkmark or a red x plus a hint, and the command exits non-zero if any fail.

### In CI?

Run linkerd check --pre before linkerd install so an unsupported cluster fails early, then run linkerd check after install as a deploy gate. The certificate checks are especially valuable: they catch trust anchors nearing expiry before they take the mesh down.

### Common errors in CI?

A failing line looks like "x control plane pods are ready" with a hint below, or "√ ... [FAIL]". "certificate will expire ... in Xh" flags an expiring trust anchor. "linkerd-config ... not found" means the control plane is not installed. "control plane version ... proxy version ... mismatch" warns a data-plane upgrade is pending.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt