cri-tools

cri-tools provides debugging and validation tools for the Kubelet Container Runtime Interface (CRI). It consists of two primary tools:

• crictl: A CLI tool used for interacting with and debugging the Kubelet CRI.
• critest: A suite of validation tests used to verify Kubelet CRI compliance.

Important Scope Note: crictl is intended for debugging. It is not a replacement for managing pods/containers via the Kubernetes API server. For example, pods created via crictl may be automatically removed by the Kubelet because they do not exist in the kube-apiserver state.

CRI tools is a suite of tools designed for the Kubelet Container Runtime Interface (CRI). It is built to be portable, easy to use, and compatible with all CRI-compliant container runtimes. It serves two primary purposes: helping runtime maintainers with validation and providing debugging capabilities.

The project consists of two main components:

1. critest: A suite used for validation and performance benchmarking.
2. crictl: A Command Line Interface (CLI) designed for interacting with the Kubelet CRI.

Due to CRI API limitations, when you use crictl rmi with an image tag (e.g., localhost/test:latest), the entire image and all its associated tags will be removed. This differs from tools like docker rmi or nerdctl rmi, which only remove the specific tag.

If you need to remove only a single tag, use the native runtime CLI:

• containerd: nerdctl image rm <tag> or ctr image rm <tag>
• CRI-O: podman rmi <tag>
• Docker: docker rmi <tag>

To ensure full support for all Container Runtime Interface (CRI) features, it is highly recommended to use a cri-tools version that matches your Kubernetes minor version.

cri-tools follows Kubernetes release cycles for minor versions (e.g., 1.x.y). While patch releases (1.x.z) for Kubernetes and cri-tools may not be perfectly synchronized, they are generally compatible within the same minor version. If a Kubernetes release reaches End of Life, the corresponding cri-tools version should also be considered at end of life.

To connect to a CRI-compatible runtime, crictl needs to know the endpoint for the runtime service and the image service. You can configure these in three ways:

1. Global Flags: Use --runtime-endpoint (-r) and --image-endpoint (-i) with your commands.
2. Environment Variables: Set CONTAINER_RUNTIME_ENDPOINT and IMAGE_SERVICE_ENDPOINT.
3. Config File: Specify a file using --config=/path/to/config.yaml or set the CRI_CONFIG_FILE environment variable. The default location is /etc/crictl.yaml.

Note: While crictl attempts to connect to default sockets (like containerd.sock or crio.sock) if no endpoint is provided, this behavior is deprecated. You should always explicitly set the runtime endpoint to avoid connection timeouts and performance issues.

Before running critest, ensure the following conditions are met:

1. CRI Server Availability: The CRI server under test must be running and listening on a Unix socket or a Windows named pipe.
2. Exclusive Access: The benchmark tests are designed to request changes (e.g., create/delete) and verify status. To ensure accuracy, the CRI server should not have other active users. Specifically:
   • There should be no existing CRI-managed containers running on the node.
   • No other processes (such as kubelet) should be interacting with the CRI server during the test.

To perform CRI validation testing, download the critest binary from the official releases page. The following steps demonstrate how to install version v1.36.0 for amd64 on Linux:

1. Download the tarball.
2. Extract it to /usr/local/bin.
3. Clean up the downloaded file.

VERSION="v1.36.0"
ARCH="amd64"
wget https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/critest-$VERSION-linux-$ARCH.tar.gz
sudo tar zxvf critest-$VERSION-linux-$ARCH.tar.gz -C /usr/local/bin
rm -f critest-$VERSION-linux-$ARCH.tar.gz

Prerequisites

Before running tests, ensure the CRI server under test is running and listening on a Unix socket.

Important Constraints:

• The CRI server must be the only user of the node.
• Ensure there are no existing CRI-managed containers running.
• Ensure no other processes (like kubelet) will interfere with the tests, as the tests perform destructive operations (create/delete) to verify status reporting.

Execution

Run the command critest to connect to the default CRI shim and execute the test suite. By default, it attempts to connect to:

• Linux (containerd): unix:///run/containerd/containerd.sock
• Windows (containerd): npipe:////./pipe/containerd-containerd

If your runtime uses a different endpoint, use the --runtime-endpoint and --image-endpoint flags.

To execute the benchmarking suite, use the critest -benchmark command. By default, critest attempts to connect to the containerd socket (unix:///run/containerd/containerd.sock on Linux or npipe:////./pipe/containerd-containerd on Windows).

If you are using a different runtime, you must specify the --runtime-endpoint and/or --image-endpoint.

critest -benchmark
    [--benchmarking-params-file /path/to/params.yml]
    [--benchmarking-output-dir /path/to/outdir/]

Containers can be managed in several ways:

1. Two-step creation: Use crictl create <pod-id> <container-config.json> <pod-config.json> to create a container in a Created state, then crictl start <container-id> to run it.
2. Single-step run: Use crictl run <container-config.json> <pod-config.json> to pull the image (if necessary), create, and start the container in one command.
3. Execution: Use crictl exec -i -t <container-id> <command> to run a command inside a running container.

You can build and install the cri-tools binaries (crictl and critest) by following these steps in the repository root:

1. Install dependencies: Run make install.tools.
2. Build and install: Run make && make install. (Note: You may need to prefix with sudo if you encounter permission issues).

After installation, verify the binaries are in your path (typically /usr/local/bin/) using which.

$ make install.tools
$ make && make install

$ which crictl
/usr/local/bin/crictl

$ which critest
/usr/local/bin/critest