# kumactl inspect: Inspect Kuma Mesh State

> kumactl inspect shows the state of Kuma dataplanes, meshes, and policies. Reference for the inspect subcommands and the control-plane errors in CI.

Source: https://latchkey.dev/learn/command-reference/kumactl-inspect  
Updated: 2026-06-30

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

```Terminal
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 default
```

## Options

| 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.

```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

### kumactl inspect: Inspect Kuma Mesh State?

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.

### 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.

---

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