cri-tools: crictl and critest for Kubernetes CRI Node Debugging

crictl connects directly to the container runtime socket, bypassing kubelet

When something breaks at a Kubernetes node, kubectl reports pod state as the kube-apiserver sees it. That view passes through kubelet before reaching the container runtime. crictl skips both and calls the Container Runtime Interface directly, giving operators raw container and sandbox state from the runtime itself.

Two tools ship together in this repository. crictl is an interactive CLI for inspecting and manipulating containers and pods at the CRI level. critest runs a structured validation suite against a runtime to confirm it implements the CRI specification correctly. Both tools target people responsible for Kubernetes nodes: platform engineers setting up new runtimes, SREs debugging stuck pods, and runtime developers confirming CRI compliance. A runtime that passes kubelet's basic health checks might still fail on specific CRI calls; crictl surfaces that gap by issuing those calls directly and showing the raw response.

gRPC, OpenTelemetry traces, and the go.mod dependency chain

crictl speaks the CRI protocol over gRPC. The go.mod lists `google.golang.org/grpc v1.84.0` and `k8s.io/cri-api v0.37.1`. The `k8s.io/cri-api` package holds the Protocol Buffer service definitions for the Container Runtime Interface; cri-tools consumes it rather than defining its own protocol. The go.mod also includes `go.opentelemetry.io/otel v1.47.0` and its OTLP gRPC exporter, meaning crictl can emit traces to an OpenTelemetry collector when configured to do so. The Makefile sets CGO_ENABLED to 0 and passes -trimpath via GOFLAGS, producing a statically linked binary with no C runtime dependency and no embedded build paths in stack traces.

One detail a README skim misses: go.mod specifies `go 1.27.0` as the minimum toolchain requirement. The README covers only the wget binary install path and says nothing about Go. Engineers packaging cri-tools from source, or building it inside a CI pipeline, need a Go 1.27 or later toolchain. The install section gives no warning about this requirement, which makes it an invisible prerequisite for anyone building rather than downloading.

Installing crictl and critest on Linux amd64

The project distributes pre-built binaries through GitHub. No package manager installation is documented in the README. To install crictl at v1.37.0:

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

The archive extracts the `crictl` binary into `/usr/local/bin`, ready to call against the configured CRI endpoint. A matching sequence installs critest:

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

The complete command reference for crictl lives in `docs/crictl.md` in the repository. Performance benchmarking instructions are in `docs/benchmark.md`, and the validation test suite documentation is in `docs/validation.md`.

Kubernetes and cri-tools version compatibility

The README contains an explicit compatibility matrix mapping each Kubernetes minor to a corresponding cri-tools minor. For Kubernetes 1.27 and above, all cri-tools builds come from the master branch. Kubernetes 1.8 through 1.15 each have a dedicated branch, created only when a patch for that minor line was planned. The matrix reaches back to v0.1 for Kubernetes 1.7.

Diverging from the recommended pairing is explicitly flagged as a risk: new CRI features may not be fully supported when the two sides differ. Patch cadences diverge as well. Kubernetes patches monthly; cri-tools cuts patch builds only when necessary. When a Kubernetes minor goes End of Life, the matching cri-tools minor is considered end-of-life by the same definition. Current and future milestones are tracked in `docs/roadmap.md`.

critest runs the official CRI validation suite and CI covers containerd and CRI-O

critest accepts a runtime endpoint and runs a structured test suite against it. The test framework is Ginkgo; go.mod lists it as `github.com/onsi/ginkgo/v2 v2.33.0` alongside the gomega matcher library at `github.com/onsi/gomega v1.44.0`. Rather than informal manual checks, runtime developers get a repeatable pass or fail against the actual specification.

The project's own CI runs separate workflows for containerd and CRI-O, visible as the "critest containerd" and "CRI-O" build status badges at the top of the README. A runtime that passes the general build workflow but fails critest would show up there. Anyone writing a new CRI-compliant runtime should treat a critest clean run as a required gate before claiming compatibility, because that is the bar the project sets for its own CI.

crictl-created pods may be removed by kubelet

The README scope section is explicit: managing pods and containers for CRI-compatible runtimes by end-users is listed as outside the project's scope. The reason given is direct: pods created by crictl may be removed automatically by kubelet because of non-existence on the kube-apiserver.

kubelet runs a reconciliation loop. A sandbox pod that has no corresponding Pod object in the apiserver is treated as orphaned and can be garbage-collected. crictl offers no mechanism to register a pod with the apiserver. That makes it a diagnostic tool, not a workload management interface. An operator who starts a container through crictl to probe a runtime configuration should be aware that kubelet may clean it up. Running long-lived workloads through crictl is the wrong use of the tool.

ctr and nerdctl cover containerd's native API rather than the CRI layer

ctr ships with containerd and speaks containerd's own API directly, not the CRI protocol. It gives lower-level access to containerd internals but works only with containerd. nerdctl provides a Docker-compatible command interface on top of containerd, also below the CRI layer. Neither tool connects to CRI-O or validates CRI specification compliance.

crictl works across any CRI-compliant runtime. An operator who needs to inspect both containerd and CRI-O nodes from the same command interface uses crictl rather than maintaining two separate runtime-specific tools. The trade-off is narrower: less access to runtime-specific internals in exchange for consistent behavior across every runtime that passes the CRI contract.

The project carries an Apache-2.0 licence. The last push was on 2026-10-06.

Editorial conclusion

cri-tools fits Kubernetes operators who need node-level container runtime inspection, where kubectl does not reach. critest belongs in the CI pipeline of anyone validating a CRI-compliant runtime before production. The tool is not a workload management interface; crictl-created pods have no kube-apiserver record and kubelet removes them. Verify the minor pairing first: cri-tools minor must match Kubernetes minor on the node. Building from source requires Go 1.27, which go.mod states but the README omits. For containerd-only clusters, runtime-specific tooling may suffice; crictl is right when CRI runtime portability matters.

Frequently asked questions

Official sources

1. Issues
2. kubernetes-sigs/cri-tools on GitHub
3. License: Apache-2.0
4. README
5. Releases