linkerd check: Gate CI on Mesh Health
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
# 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-appOptions
| 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.