kumactl inspect: Inspect Kuma Mesh State
kumactl inspect queries the Kuma control plane for the live state of dataplanes, meshes, zones, and policy matching.
After deploying Kuma workloads, kumactl inspect dataplanes confirms every proxy connected to the control plane and is online, which is your readiness gate.
What it does
kumactl inspect reports live mesh state from the control plane. inspect dataplanes lists proxies and their status, inspect meshes shows configured meshes, and inspect dataplane <name> shows which policies apply to one proxy. It talks to the control-plane API, so the CP must be reachable.
Common usage
kumactl inspect dataplanes
# limit to a mesh
kumactl inspect dataplanes --mesh default
# what policies apply to one dataplane
kumactl inspect dataplane my-app-0 --mesh defaultOptions
| Subcommand / flag | What it does |
|---|---|
| inspect dataplanes | List all dataplanes and their status |
| inspect meshes | List configured meshes |
| inspect dataplane <name> | Show policies matched for one dataplane |
| --mesh <name> | Scope the query to a mesh |
| -o json|yaml | Structured output for CI assertions |
In CI
Poll kumactl inspect dataplanes -o json after a deploy and fail if any expected dataplane is missing or Offline. Point kumactl at the CP with the KUMACTL config or --config-file so the CI runner reaches the right control plane.
Common errors in CI
"Could not connect to the Control Plane API Server ... connection refused" means the CP address is wrong or the CP is down; run kumactl config control-planes list. A dataplane showing Offline means the proxy lost its connection to the CP. "no such mesh" from --mesh means the mesh name is misspelled or not created yet.
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