crictl provides a CLI for CRI-compatible container runtimes. This allows the CRI runtime developers to debug their runtime without needing to set up Kubernetes components.
crictl is currently in Beta and still under quick iterations. It is hosted at the cri-tools repository. We encourage the CRI developers to report bugs or help extend the coverage by adding more functionalities.
crictl
can be downloaded from cri-tools release page:
- using
wget
:
VERSION="v1.17.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
- using
curl
:
VERSION="v1.17.0"
curl -L https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-${VERSION}-linux-amd64.tar.gz --output 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
crictl SUBCOMMAND [FLAGS]
Subcommands includes:
attach
: Attach to a running containercreate
: Create a new containerexec
: Run a command in a running containerversion
: Display runtime version informationimages, image, img
: List imagesinspect
: Display the status of one or more containersinspecti
: Return the status of one or more imagesimagefsinfo
: Return image filesystem infoinspectp
: Display the status of one or more podslogs
: Fetch the logs of a containerport-forward
: Forward local port to a podps
: List containerspull
: Pull an image from a registryrun
: Run a new container inside a sandboxrunp
: Run a new podrm
: Remove one or more containersrmi
: Remove one or more imagesrmp
: Remove one or more podspods
: List podsstart
: Start one or more created containersinfo
: Display information of the container runtimestop
: Stop one or more running containersstopp
: Stop one or more running podsupdate
: Update one or more running containersconfig
: Get and set crictl optionsstats
: List container(s) resource usage statisticscompletion
: Output bash shell completion codehelp, h
: Shows a list of commands or help for one command
crictl by default connects to Unix: unix:///var/run/dockershim.sock
or Windows: tcp://localhost:3735
. For other runtimes, use:
- containerd:
unix:///run/containerd/containerd.sock
- cri-o:
unix:///var/run/crio/crio.sock
- frakti:
unix:///var/run/frakti.sock
The endpoint can be set in three ways:
- By setting flags
--runtime-endpoint
(-r
) and--image-endpoint
(-i
) - By setting environment variables
CONTAINER_RUNTIME_ENDPOINT
andIMAGE_SERVICE_ENDPOINT
- By setting the endpoint in the config file
--config=/etc/crictl.yaml
Unix:
$ cat /etc/crictl.yaml
runtime-endpoint: unix:///var/run/dockershim.sock
image-endpoint: unix:///var/run/dockershim.sock
timeout: 10
debug: true
Windows:
C:\> type %USERPROFILE%\.crictl\crictl.yaml
runtime-endpoint: tcp://localhost:3735
image-endpoint: tcp://localhost:3735
timeout: 10
debug: true
Some runtimes might use cmux for connection
multiplexing, which can cause issues during the initial gRPC
connection setup. If it does not seem to be possible to connect to the runtime
*.sock
, then exporting the environment variable
GRPC_GO_REQUIRE_HANDSHAKE=off
might solve the issue. Please take into account
that the environment has to be preserved when running
via sudo (sudo -E crictl ...
).
--timeout
,-t
: Timeout of connecting to server (default: 10s)--debug
,-D
: Enable debug output--help
,-h
: show help--version
,-v
: print the version information of crictl--config
,-c
: Config file in yaml format. Overrided by flags or environment variables.
$ cat pod-config.json
{
"metadata": {
"name": "nginx-sandbox",
"namespace": "default",
"attempt": 1,
"uid": "hdishd83djaidwnduwk28bcsb"
},
"log_directory": "/tmp",
"linux": {
}
}
$ crictl runp pod-config.json
f84dd361f8dc51518ed291fbadd6db537b0496536c1d2d6c05ff943ce8c9a54f
List pod sandboxes and check the sandbox is in Ready state:
$ crictl pods
POD ID CREATED STATE NAME NAMESPACE ATTEMPT
f84dd361f8dc5 17 seconds ago Ready busybox-sandbox default 1
Runtime handler requires runtime support. The following example shows running a pod sandbox with runsc
handler on containerd runtime.
$ cat pod-config.json
{
"metadata": {
"name": "nginx-runsc-sandbox",
"namespace": "default",
"attempt": 1,
"uid": "hdishd83djaidwnduwk28bcsb"
},
"log_directory": "/tmp",
"linux": {
}
}
$ crictl runp --runtime=runsc pod-config.json
c112976cb6caa43a967293e2c62a2e0d9d8191d5109afef230f403411147548c
$ crictl inspectp c112976cb6caa43a967293e2c62a2e0d9d8191d5109afef230f403411147548c
...
"runtime": {
"runtimeType": "io.containerd.runtime.v1.linux",
"runtimeEngine": "/usr/local/sbin/runsc",
"runtimeRoot": "/run/containerd/runsc"
},
...
$ crictl pull busybox
Image is up to date for busybox@sha256:141c253bc4c3fd0a201d32dc1f493bcf3fff003b6df416dea4f41046e0f37d47
List images and check the busybox image has been pulled:
$ crictl images
IMAGE TAG IMAGE ID SIZE
busybox latest 8c811b4aec35f 1.15MB
k8s.gcr.io/pause 3.1 da86e6ba6ca19 742kB
$ cat pod-config.json
{
"metadata": {
"name": "nginx-sandbox",
"namespace": "default",
"attempt": 1,
"uid": "hdishd83djaidwnduwk28bcsb"
},
"log_directory": "/tmp",
"linux": {
}
}
$ cat container-config.json
{
"metadata": {
"name": "busybox"
},
"image":{
"image": "busybox"
},
"command": [
"top"
],
"log_path":"busybox.0.log",
"linux": {
}
}
$ crictl create f84dd361f8dc51518ed291fbadd6db537b0496536c1d2d6c05ff943ce8c9a54f container-config.json pod-config.json
3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
List containers and check the container is in Created state:
$ crictl ps -a
CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT
3e025dd50a72d busybox 32 seconds ago Created busybox 0
$ crictl start 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
$ crictl ps
CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT
3e025dd50a72d busybox About a minute ago Running busybox 0
crictl exec -i -t 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60 ls
bin dev etc home proc root sys tmp usr var
It is possible to start a container within a single command, whereas the image will be pulled automatically, too:
$ cat pod-config.json
{
"metadata": {
"name": "nginx-sandbox",
"namespace": "default",
"attempt": 1,
"uid": "hdishd83djaidwnduwk28bcsb"
},
"log_directory": "/tmp",
"linux": {
}
}
$ cat container-config.json
{
"metadata": {
"name": "busybox"
},
"image":{
"image": "busybox"
},
"command": [
"top"
],
"log_path":"busybox.0.log",
"linux": {
}
}
$ crictl run container-config.json pod-config.json
b25b4f26e342969eb40d05e98130eee0846557d667e93deac992471a3b8f1cf4
List containers and check the container is in Running state:
$ crictl ps
CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID
b25b4f26e3429 busybox:latest 14 seconds ago Running busybox 0 158d7a6665ff3
- See the Kubernetes.io Debugging Kubernetes nodes with crictl doc
- Visit kubernetes-sigs/cri-tools for more information.