crictl Commands
crictl is the essential tool for debugging containers on Kubernetes nodes. Learn to inspect pods, containers, and images directly on the node without kubectl.
Pods
Containers
Images
What is crictl?
crictl is a command-line interface for CRI-compatible container runtimes. It allows you to interact with containers, pods, and images on a Kubernetes node without going through the Kubernetes API server. It's the primary tool for debugging container issues at the node level.
Unlike kubectl (which communicates with the API server), crictl communicates directly with the container runtime. This makes it invaluable for troubleshooting node-level issues when the API server is unavailable or when you need to inspect containers directly.
crictl is the go-to tool for Kubernetes node debugging. If you're troubleshooting a pod that won't start or a node that's misbehaving, crictl is your best friend.
Installing crictl
# Install latest version
VERSION="v1.28.0"
curl -L https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-$VERSION-linux-amd64.tar.gz -o crictl.tar.gz
sudo tar Cxzvf /usr/local/bin crictl.tar.gz
# Verify installation
crictl --version
# Configure crictl endpoint (default for containerd)
export CONTAINER_RUNTIME_ENDPOINT=unix:///run/containerd/containerd.sock
# Or set in /etc/crictl.yaml
cat > /etc/crictl.yaml <
Pod Commands
crictl pods
List all pods on the node
crictl pods --name nginx
Filter pods by name
crictl pods --namespace kube-system
Filter pods by namespace
crictl pods --state Ready
Filter by pod state
crictl inspectp <pod-id>
Inspect a pod
crictl rm <pod-id>
Remove a pod (sandbox)
# List all pods
crictl pods
# Example output:
POD ID CREATED STATE NAME NAMESPACE
abc123def456 2 minutes ago Ready nginx-deployment default
def456ghi789 5 minutes ago Ready kube-proxy-abc kube-system
# List pods with details
crictl pods -v
# Get pod by label
crictl pods --label app=nginx
Container Commands
crictl ps
List running containers
crictl ps -a
List all containers
crictl inspect <id>
Inspect a container
crictl logs <id>
View container logs
crictl exec <id> <cmd>
Execute command in container
crictl stop <id>
Stop a container
crictl rm <id>
Remove a container
# List running containers
crictl ps
# List all containers (including stopped)
crictl ps -a
# Get container details
crictl inspect
# View container logs
crictl logs
# Follow logs
crictl logs -f
# Execute command
crictl exec -it sh
# Get container stats
crictl stats
Image Commands
crictl images
List images
crictl inspecti <image>
Inspect an image
crictl pull <image>
Pull an image
crictl rmi <image>
Remove an image
# List images
crictl images
# List images with details
crictl images -v
# Pull image
crictl pull nginx:alpine
# Inspect image
crictl inspecti nginx:alpine
# Remove image
crictl rmi nginx:alpine
Common Debugging Workflows
# 1. Find a pod that's failing
kubectl get pods -n myapp
# Pod is in CrashLoopBackOff or Pending
# 2. SSH to the node (or use node debug)
# 3. Find the pod on the node
crictl pods --name
# 4. Get container ID
crictl ps -a | grep
# 5. Inspect container logs
crictl logs
# 6. Inspect container details
crictl inspect | jq '.status'
# 7. Get detailed pod info
crictl inspectp | jq '.status'
# 8. Check container stats
crictl stats
Advanced Commands
# Get runtime information
crictl info
# Check CRI version
crictl version
# Get container state in JSON
crictl inspect --output json
# Get pod sandbox info
crictl inspectp --output yaml
# Filter containers by label
crictl ps --label app=nginx
# Filter containers by state
crictl ps --state Running
crictl ps --state Exited
# Remove all stopped containers
crictl ps -a | grep Exited | awk '{print $1}' | xargs -r crictl rm
crictl vs kubectl
- kubectl: Communicates with Kubernetes API server. Works across the entire cluster. Uses RBAC for authentication.
- crictl: Communicates directly with container runtime on a specific node. Works even if API server is down. Requires node access.
Use kubectl for cluster-wide operations and crictl for node-level debugging. They complement each other.
Troubleshooting crictl
# Check if crictl can connect
crictl info
# Error: "failed to connect"
# Check runtime endpoint
cat /etc/crictl.yaml
export CONTAINER_RUNTIME_ENDPOINT=unix:///run/containerd/containerd.sock
# Check containerd status
sudo systemctl status containerd
# Check if containerd is listening on the socket
ls -la /run/containerd/containerd.sock
# Debug with verbose output
crictl --debug ps
Frequently Asked Questions
What's the difference between crictl and docker commands?
crictl is specifically designed for CRI-compatible runtimes (containerd, CRI-O). Docker commands work only with Docker Engine. crictl is the standard tool for Kubernetes node debugging.
Can I use crictl with Docker Engine?
No. crictl works with CRI-compatible runtimes (containerd, CRI-O). For Docker Engine, use `docker` commands directly or the cri-dockerd adapter.
How do I find the container ID for a pod?
Use `crictl pods --name ` to get the pod ID, then `crictl ps -a | grep ` to find container IDs.
Is crictl installed on Kubernetes nodes by default?
Not always. Some distributions include it, but you may need to install it. It's highly recommended for production nodes.
Can I use crictl with CRI-O?
Yes! crictl works with any CRI-compatible runtime. For CRI-O, use the endpoint `unix:///var/run/crio/crio.sock`.
How do I see logs for a container that has stopped?
Use `crictl ps -a` to find the container ID, then `crictl logs ` to view logs, even if the container is stopped.
What's the difference between crictl and kubectl logs?
`kubectl logs` shows logs from the Kubernetes API. `crictl logs` shows logs directly from the container runtime. Use crictl when kubectl isn't available or when you need lower-level details.
Can I inspect pod metadata with crictl?
Yes! `crictl inspectp ` shows pod metadata including labels, annotations, and container status.
Master crictl to debug Kubernetes nodes effectively. It's the essential tool for every Kubernetes administrator and developer.