crictl

What it is and where it fits 🎯#

crictl talks directly to a node's container runtime over the CRI (Container Runtime Interface) gRPC socket — the same interface the kubelet itself uses — bypassing the kubelet and the Kubernetes API server entirely. That makes it the tool for exactly one situation: something is wrong below Kubernetes' own view of the world, and kubectl either can't see it or the API server isn't answering at all. kubectl describe pod tells you what Kubernetes thinks is happening to a Pod; crictl inspect tells you what the runtime is actually doing with the containers behind it — the two can disagree, and when they do, crictl is how you find out which one is lying. It's runtime-agnostic by design (works identically against containerd, CRI-O, or any other CRI implementation) — install it alongside kubeadm/kubelet on any node you'll ever need to debug directly.

Where crictl sits in the stack#

crictl and the kubelet are peers talking to the same socket, not a client-of-a-client — this is why crictl can see (and, dangerously, change) container state the kubelet doesn't know about yet, which is exactly the source of the biggest pitfall covered below.

Installation#

# Pin the crictl version to your cluster's Kubernetes MINOR version, not "latest" —
# cri-tools follows the k8s release cycle and mismatched minors can behave subtly differently.
VERSION="v1.36.0"
curl -LO "https://github.com/kubernetes-sigs/cri-tools/releases/download/${VERSION}/crictl-${VERSION}-linux-amd64.tar.gz"
sudo tar -C /usr/local/bin -xzf "crictl-${VERSION}-linux-amd64.tar.gz"
rm "crictl-${VERSION}-linux-amd64.tar.gz"

crictl --version

Configuring the runtime endpoint#

crictl config --set runtime-endpoint=unix:///run/containerd/containerd.sock
crictl config --set image-endpoint=unix:///run/containerd/containerd.sock
crictl config --get runtime-endpoint
crictl config --list
crictl --runtime-endpoint unix:///run/containerd/containerd.sock ps    # override per-invocation instead

Real captured output from this sandbox — no config file exists and no CRI socket is reachable, which is exactly the failure shape you'll see running crictl on a machine that either doesn't have containerd/CRI-O running or where you lack permission on the socket:

Config file format#

# /etc/crictl.yaml
runtime-endpoint: unix:///run/containerd/containerd.sock
image-endpoint: unix:///run/containerd/containerd.sock
timeout: 10
debug: false
pull-image-on-create: false

timeout is the connection timeout in seconds (default 2s) — worth raising on a node under heavy load where the runtime's gRPC server is slow to respond, rather than crictl reporting a spurious connection failure that's really just a timeout.

Listing pods, containers, and images#

crictl pods                                     # every pod sandbox the runtime knows about
crictl ps                                        # running containers only
crictl ps -a                                      # every container, including exited/created ones
crictl ps --state Running --label app=catalog-api  # filter by state and label, same idea as `kubectl get pods -l`
crictl images                                     # every image cached on this node
crictl images --filter dangling=true              # untagged/orphaned image layers
crictl stats                                       # live CPU/memory per container, like `docker stats`

crictl ps output columns (CONTAINER, IMAGE, CREATED, STATE, NAME, ATTEMPT, POD ID, POD) map closely to what kubectl get pods -o wide shows for a Pod's containers, but sourced straight from the runtime — useful specifically when the two disagree.

Illustrative crictl ps -a table shape (this node has no CRI runtime reachable, so this reflects the documented column layout rather than a live capture — mark it as such if you paste it anywhere):

Inspecting and debugging#

crictl inspect <container-id>                     # full container JSON: config, mounts, env, state
crictl inspectp <pod-id>                            # the pod sandbox's own network namespace/config
crictl logs <container-id>                           # like `kubectl logs`, but reads straight from the runtime's log path
crictl logs -f --tail 100 <container-id>
crictl exec -it <container-id> /bin/sh              # like `kubectl exec`, no API server round-trip
crictl attach <container-id>                          # attach to PID 1's stdio instead of spawning a new process
crictl info                                            # runtime version, config, and CNI plugin status for the whole node

Managing images directly#

crictl pull myregistry.io/myapp:latest                       # pull without creating a container from it
crictl pull --creds myuser:mypass myregistry.io/myapp:latest   # authenticated pull, credentials never touch a container's env
crictl rmi <image-id>                                          # remove one image
crictl rmi --prune                                              # remove every image not referenced by any container/pod

Low-level container lifecycle: create, run, and stop#

crictl runp pod-config.yaml                          # create a new pod sandbox (network namespace, etc.)
crictl create <pod-id> container-config.yaml pod-config.yaml   # create a container inside an existing sandbox
crictl start <container-id>                            # start a created-but-not-started container
crictl run container-config.yaml pod-config.yaml        # runp + create + start in one call — the closest thing to `docker run`
crictl stop <container-id>
crictl stopp <pod-id>                                    # stop every container in a pod sandbox at once
crictl rm <container-id>
crictl rmp <pod-id>

These commands take structured JSON/YAML config files (a PodSandboxConfig/ContainerConfig, the same shapes the kubelet itself builds from a Pod spec), not simple image-name-and-flags the way docker run does — crictl create <id> --help lists a jsonschema subcommand that prints the exact schema expected. Reach for these only for genuinely low-level runtime testing/debugging (confirming the runtime itself can start a container at all, independent of anything Kubernetes-shaped) — see the CAUTION above on why this isn't a routine workload-management path.

Streaming events and forwarding a port for debugging#

crictl events                                          # stream container/pod lifecycle events live, like `kubectl get events -w` but runtime-sourced
crictl port-forward <pod-id> 8080:80                     # forward a local port into a pod sandbox, bypassing kube-apiserver entirely

crictl port-forward is the direct-to-node equivalent of kubectl port-forward — genuinely useful when the API server itself is the thing that's down and kubectl port-forward can't establish its usual proxied connection through it.

Real-world scenario: debugging when the API server is unreachable#

A control-plane outage means kubectl can't talk to anything, but workloads on healthy worker nodes are still running — SSH onto the affected node and go straight to the runtime:

crictl ps -a                       # is the container actually still running, or did it crash silently?
crictl inspect <container-id>       # exact exit code, OOM status, and restart count from the runtime's own record
crictl logs --tail 200 <container-id>

This is the scenario crictl exists for — every one of these facts is normally surfaced through kubectl, but only because the kubelet reports them up to an API server that, in this scenario, isn't there to receive the report.

Real-world scenario: confirming what image tag actually got pulled#

A team suspects a :latest-tagged deployment is running stale code because the registry's :latest moved but the node's local image cache didn't get refreshed:

crictl images --digests | grep myapp
crictl inspecti myapp:latest | grep -A2 '"repoDigests"'

Comparing the repoDigests crictl reports against the digest currently pushed in the registry proves definitively whether the node is running the image it thinks it's running — a kubectl describe pod alone only shows the tag, which by definition can't prove what it currently points to.

Real-world scenario: recovering a node with a wedged container#

A container is stuck in Terminating for far longer than its terminationGracePeriodSeconds, and kubectl delete pod --force isn't clearing it because the kubelet itself is the thing stuck waiting on the runtime:

crictl ps -a --state Running | grep <pod-name>
crictl stop <container-id>              # ask the runtime directly to stop it
crictl stop --timeout 0 <container-id>   # skip graceful shutdown entirely if it's truly hung
crictl rm <container-id>

Shell completion#

source <(crictl completion bash)     # bash, current session
crictl completion zsh > "${fpath[1]}/_crictl"   # zsh, persistent
crictl completion fish | source       # fish

Common pitfalls#

• Running crictl without root or the right group membership on the CRI socket — the real captured error above (connect: permission denied) is exactly this; the socket is root-owned by default on most distributions.
• Trusting default endpoint auto-detection — see the IMPORTANT callout above; set runtime-endpoint explicitly.
• Mismatched crictl/Kubernetes minor versions — an old crictl against a newer CRI API (or vice versa) can silently miss fields the newer/older side added; pin crictl's version to the cluster's.
• Using crictl rm/stop as routine Pod management — see the CAUTION above; it fights the kubelet's own reconciliation instead of working with it.
• Forgetting -a on ps/pods and concluding a container "doesn't exist" when it's actually just not in the Running state crictl shows by default.
• Expecting crictl rmi <tag> to behave like docker rmi <tag> — see the WARNING above; it removes the whole image, every tag, not just the one named.

Choosing a debugging tool at this layer#

Exit codes and when to reach for something else#

0 on success; non-zero on any RPC failure to the CRI socket (connection refused, permission denied, timeout) or a not-found ID. The verbose error text (see the captured example above) almost always states which of the three things went wrong — no socket, no permission, or no such runtime — directly in the message.

Reach for kubectl logs/kubectl exec/kubectl describe first, always — they're the supported, RBAC-aware path and work identically regardless of which CRI implementation a node runs. Drop down to crictl specifically when the API server is unreachable, when you suspect the kubelet's view of a container has drifted from reality, or when debugging the runtime/CNI layer itself rather than a specific workload. kubeadm (this category's companion cheat sheet) is what installs the node in the first place; crictl is what you reach for once something on that node needs a closer look.