CRI-O Container CLI

What it is

crictl is the command-line interface for interacting with CRI (Container Runtime Interface) compatible container runtimes like CRI-O and containerd, allowing you to inspect and debug running containers.

Installation

Linux

CRI-O is typically installed via your distribution’s package manager. For example, on Fedora/CentOS/RHEL:

sudo dnf install cri-o
# or
sudo yum install cri-o

On Ubuntu/Debian:

sudo apt update
sudo apt install cri-o

crictl is usually installed as part of the cri-o package or a separate cri-tools package.

macOS

crictl is not typically installed directly on macOS. You would usually interact with a container runtime running inside a VM or a remote environment.

Windows

crictl is not typically installed directly on Windows. Similar to macOS, interaction would be with a remote or VM-based container runtime.

Core Concepts

• Pod: A group of one or more containers sharing the same network namespace and storage volumes. CRI-O manages pods.
• Container: An isolated process running within a pod.
• Image: A read-only template used to create containers.
• Runtime: The underlying software that runs containers (e.g., CRI-O, containerd). crictl communicates with this runtime via the CRI API.
• Sandbox: In CRI terminology, a sandbox is the environment that hosts one or more containers, typically corresponding to a Kubernetes Pod.

Commands / Usage

Inspecting Pods and Containers

Listing Pods

crictl pods

List all pods managed by the container runtime.

crictl pods --namespace kube-system

List pods within a specific namespace.

Inspecting a Pod

crictl inspectp <pod-id>

Get detailed information about a specific pod (e.g., 01b2c3d4e5f6a7b8c9d0).

Listing Containers

crictl ps

List all running containers.

crictl ps -a

List all containers, including stopped ones.

crictl ps --pod <pod-id>

List containers belonging to a specific pod.

Inspecting a Container

crictl inspect <container-id>

Get detailed information about a specific container (e.g., abcdef123456).

Getting Container Logs

crictl logs <container-id>

Fetch logs from a container.

crictl logs <container-id> --tail 100

Fetch the last 100 lines of logs from a container.

crictl logs <container-id> -f

Stream logs from a container in real-time.

Executing Commands in a Container

crictl exec <container-id> -- ls /app

Execute a command inside a running container.

crictl exec <container-id> -- bash

Start an interactive shell session within a running container.

Managing Images

Listing Images

crictl images

List all container images available on the runtime.

Inspecting an Image

crictl inspecti <image-id-or-name>

Get detailed information about a container image (e.g., docker.io/library/nginx:latest or sha256:abcdef123456...).

Pulling Images

crictl pull docker.io/library/ubuntu:latest

Download a container image from a registry.

Removing Images

crictl rmi <image-id-or-name>

Remove a specific container image.

crictl rmi --prune

Remove all unused images.

Managing Containers and Pods

Running a Container (Standalone - not typically done outside of Kubernetes)

crictl run --image docker.io/library/nginx:latest --name my-nginx-container my-nginx-pod

Create and start a container within a new pod. This is a lower-level operation; Kubernetes usually orchestrates this.

Starting a Container

crictl start <container-id>

Start a stopped container.

Stopping a Container

crictl stop <container-id>

Stop a running container gracefully.

Killing a Container

crictl kill <container-id>

Forcefully stop a running container.

Removing a Container

crictl rm <container-id>

Remove a stopped container.

Removing a Pod

crictl rmpod <pod-id>

Remove a pod and all its containers.

Runtime Configuration and Status

Getting Runtime Status

crictl version

Display version information about crictl and the connected runtime.

crictl info

Display general information about the container runtime.

Listing Pods (with more detail)

crictl pods -o wide

List pods with more verbose output, including IP addresses.

Inspecting Container Status

crictl ps -o json

Get container information in JSON format.

Container Stats

crictl stats

Display resource usage statistics for running containers.

Image Management

Loading Images from Tarball

crictl load -i my-image.tar

Load a container image from a tar archive.

Saving Images to Tarball

crictl save <image-id-or-name> -o my-image.tar

Save a container image to a tar archive.

Common Patterns

Get the IP address of a pod:

crictl pods -o wide | grep my-pod-name | awk '{print $4}'

Find the IP address for a pod by listing pods in wide format and filtering.

View logs for all containers in a specific pod:

POD_ID=$(crictl pods | grep my-pod-name | awk '{print $1}')
for CONTAINER_ID in $(crictl ps --pod $POD_ID | awk '{print $1}'); do
  echo "--- Logs for container $CONTAINER_ID ---"
  crictl logs $CONTAINER_ID
done

Iterate through containers of a pod and display their logs.

Exec into a container within a specific pod:

POD_ID=$(crictl pods | grep my-pod-name | awk '{print $1}')
CONTAINER_ID=$(crictl ps --pod $POD_ID | head -n 1 | awk '{print $1}') # Get the first container in the pod
crictl exec $CONTAINER_ID -- bash

Find a pod, get its first container’s ID, and start an interactive shell.

Prune unused images:

crictl rmi --prune

Clean up disk space by removing images that are not associated with any running or stopped containers.

Get raw JSON output for scripting:

crictl inspect <container-id> -o json

Useful for parsing container details programmatically.

Gotchas

• ID Ambiguity: crictl often accepts partial IDs. Be careful when using short IDs, especially if you have many containers/pods. It’s safer to use longer or full IDs where possible.
• Runtime Endpoint: crictl connects to the CRI runtime via a configured endpoint (usually a Unix domain socket like /var/run/crio/crio.sock or /run/containerd/containerd.sock). If this endpoint is misconfigured or the runtime isn’t running, crictl commands will fail. The endpoint is often specified via the CONTAINER_RUNTIME_ENDPOINT environment variable or a configuration file.
• Root Privileges: Many crictl operations (especially those involving image loading/saving or accessing runtime sockets) require root privileges (sudo).
• Kubernetes vs. Direct Usage: While crictl can run containers and pods directly, this is generally not how it’s used in production. Its primary purpose is debugging and inspection within a Kubernetes or similar orchestration environment. Direct usage bypasses the full orchestration logic.
• Container vs. Pod IDs: Be mindful of whether you’re using a container ID or a pod ID, as commands like inspect and rm behave differently depending on the ID type. inspectp is specifically for pods.
• Namespaces: crictl operates on containers and pods managed by the runtime. If you’re using Kubernetes, these are typically associated with Kubernetes namespaces, but crictl itself doesn’t directly understand Kubernetes namespaces; it sees pods based on the runtime’s internal grouping. You might need to filter pods by labels or names if you have many.