istioctl proxy-status: Check Sidecar Sync
istioctl proxy-status (aliased istioctl ps) reports the config sync state of every Envoy sidecar against what istiod last pushed.
After a deploy you want proof the mesh actually converged. proxy-status is the fastest read: every proxy should show SYNCED across CDS, LDS, EDS, and RDS.
What it does
istioctl proxy-status lists each proxy (sidecar or gateway) and, for each xDS type (CDS clusters, LDS listeners, EDS endpoints, RDS routes), whether it is SYNCED, STALE, or NOT SENT relative to istiods current config. It confirms the control plane and data plane agree.
Common usage
istioctl proxy-status
# focus on one workload
istioctl proxy-status my-app-7d9f-abcde.my-app
# short alias
istioctl psOptions
| Column / flag | What it means |
|---|---|
| SYNCED | The proxy has the latest config istiod sent |
| STALE | istiod sent an update the proxy has not acknowledged |
| NOT SENT | istiod has nothing to send yet for that xDS type |
| -n, --namespace <ns> | Limit output to a namespace |
| --revision <name> | Show proxies managed by a specific control-plane revision |
In CI
Gate a post-deploy job on proxy-status: parse the output and fail if any proxy is STALE after a grace period. A persistent STALE means the sidecar cannot reach istiod or is wedged. NOT SENT right after startup is normal and clears as config flows.
Common errors in CI
A proxy stuck at STALE for CDS or LDS usually means the sidecar lost its connection to istiod (network policy, mTLS, or istiod restart). "Error: no running Istio pods in namespace istio-system" means the control plane is not installed or is in another namespace; pass -i/--istioNamespace. "could not find cluster context" is a KUBECONFIG problem, not a mesh problem.
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.
# 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