1Container(Runtime) CLI Container(Runtime)
2 crictl provides a CLI for CRI-compatible container runtimes. This al‐
6 lows the CRI runtime developers to debug their runtime without needing
7 to set up Kubernetes components.
8 crictl is currently in Beta and still under quick iterations. It is
11 hosted at the cri-tools ⟨https://github.com/kubernetes-sigs/cri-tools⟩
12 repository. We encourage the CRI developers to report bugs or help ex‐
13 tend the coverage by adding more functionalities.
14
17 crictl can be downloaded from cri-tools release page
18 ⟨https://github.com/kubernetes-sigs/cri-tools/releases⟩:
19 • using wget:
22 VERSION="v1.24.1"
26 wget https://github.com/kubernetes-sigs/cri-tools/releases/download/$VERSION/crictl-$VERSION-linux-amd64.tar.gz
27 sudo tar zxvf crictl-$VERSION-linux-amd64.tar.gz -C /usr/local/bin
28 rm -f crictl-$VERSION-linux-amd64.tar.gz
29 • using curl:
33 VERSION="v1.24.1"
37 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
38 sudo tar zxvf crictl-$VERSION-linux-amd64.tar.gz -C /usr/local/bin
39 rm -f crictl-$VERSION-linux-amd64.tar.gz
40
44 crictl [global options] command [command options] [arguments...]
45 COMMANDS:
49 • attach: Attach to a running container
52 • create: Create a new container
54 • exec: Run a command in a running container
56 • version: Display runtime version information
58 • images, image, img: List images
60 • inspect: Display the status of one or more contain‐
62 ers
63 • inspecti: Return the status of one or more images
65 • imagefsinfo: Return image filesystem info
67 • inspectp: Display the status of one or more pods
69 • logs: Fetch the logs of a container
71 • port-forward: Forward local port to a pod
73 • ps: List containers
75 • pull: Pull an image from a registry
77 • run: Run a new container inside a sandbox
79 • runp: Run a new pod
81 • rm: Remove one or more containers
83 • rmi: Remove one or more images
85 • rmp: Remove one or more pods
87 • pods: List pods
89 • start: Start one or more created containers
91 • info: Display information of the container run‐
93 time
94 • stop: Stop one or more running containers
96 • stopp: Stop one or more running pods
98 • update: Update one or more running containers
100 • config: Get and set crictl client configuration
102 options
103 • stats: List container(s) resource usage statis‐
105 tics
106 • completion: Output bash shell completion code
108 • help, h: Shows a list of commands or help for one
110 command
111 crictl by default connects on Unix to:
115 • unix:///var/run/dockershim.sock or
118 • unix:///run/containerd/containerd.sock or
120 • unix:///run/crio/crio.sock or
122 • unix:///var/run/cri-dockerd.sock
124 or on Windows to:
128 • npipe:////./pipe/dockershim or
131 • npipe:////./pipe/containerd-containerd or
133 • npipe:////./pipe/cri-dockerd
135 For other runtimes, use:
139 • frakti ⟨https://github.com/kubernetes/frakti⟩:
142 unix:///var/run/frakti.sock
143 The endpoint can be set in three ways:
147 • By setting global option flags --runtime-endpoint (-r) and
150 --image-endpoint (-i)
151 • By setting environment variables CONTAINER_RUNTIME_ENDPOINT
153 and IMAGE_SERVICE_ENDPOINT
154 • By setting the endpoint in the config file --con‐
156 fig=/etc/crictl.yaml
157 If the endpoint is not set then it works as follows:
161 • If the runtime endpoint is not set, crictl will by default try
164 to connect using:
165 • dockershim
167 • containerd
169 • cri-o
171 • cri-dockerd
173 • If the image endpoint is not set, crictl will by default use
177 the runtime endpoint setting
178 Note: The default endpoints are now deprecated and the runtime
182 endpoint should always be set instead. The performance maybe
183 affected as each default connection attempt takes n-seconds to
184 complete before timing out and going to the next in sequence.
185 Unix:
189 $ cat /etc/crictl.yaml
192 runtime-endpoint: unix:///var/run/dockershim.sock
193 image-endpoint: unix:///var/run/dockershim.sock
194 timeout: 2
195 debug: true
196 pull-image-on-create: false
197 Windows:
201 C:\> type %USERPROFILE%\.crictl\crictl.yaml
204 runtime-endpoint: tcp://localhost:3735
205 image-endpoint: tcp://localhost:3735
206 timeout: 2
207 debug: true
208 pull-image-on-create: false
209 Connection troubleshooting
213 Some runtimes might use cmux ⟨https://github.com/soheilhy/cmux⟩ for
214 connection multiplexing, which can cause issues during the initial gRPC
215 ⟨https://grpc.io⟩ connection setup. If it does not seem to be possible
216 to connect to the runtime *.sock, then exporting the environment vari‐
217 able GRPC_GO_REQUIRE_HANDSHAKE=off might solve the issue. Please take
218 into account that the environment has to be preserved when running via
219 sudo (sudo -E crictl ...).
220
223 • --timeout, -t: Timeout of connecting to server in seconds (de‐
224 fault: 2s). 0 or less is interpreted as unset and converted
225 to the default. There is no option for no timeout value set
226 and the smallest supported timeout is 1s
227 • --debug, -D: Enable debug output
229 • --help, -h: show help
231 • --version, -v: print the version information of crictl
233 • --config, -c: Location of the client config file. If not spec‐
235 ified and the default does not exist, the program's directory
236 is searched as well (default: "/etc/crictl.yaml") [$CRI_CON‐
237 FIG_FILE]
238
242 Use the crictl config command to get and set the crictl client configu‐
243 ration options.
244 USAGE:
247 crictl config [command options] [<crictl options>]
248 For example crictl config --set debug=true will enable debug mode when
252 giving subsequent crictl commands.
253 CRICTL OPTIONS:
256 runtime-endpoint: Container runtime endpoint
259 image-endpoint: Image endpoint
260 timeout: Timeout of connecting to server (default: 2s)
261 debug: Enable debug output (default: false)
262 pull-image-on-create: Enable pulling image on create requests (default: false)
263 disable-pull-on-run: Disable pulling image on run requests (default: false)
264 OPTIONS:
269 --get value show the option value
272 --set value set option (can specify multiple or separate values with commas: opt1=val1,opt2=val2)
273 --help, -h show help (default: false)
274 When enabled pull-image-on-create modifies the create container
278 command to first pull the container's image. This feature is
279 used as a helper to make creating containers easier and faster.
280 Some users of crictl may desire to not pull the image necessary
281 to create the container. For example, the image may have al‐
282 ready been pulled or otherwise loaded into the container run‐
283 time, or the user may be running without a network. For this
284 reason the default for pull-image-on-create is false.
285 By default the run command first pulls the container image, and
288 disable-pull-on-run is false. Some users of crictl may desire
289 to set disable-pull-on-run to true to not pull the image by de‐
290 fault when using the run command.
291 To override these default pull configuration settings, --no-pull
294 and --with-pull options are provided for the create and run com‐
295 mands.
296
300 Run pod sandbox with config file
301 $ cat pod-config.json
302 {
303 "metadata": {
304 "name": "nginx-sandbox",
305 "namespace": "default",
306 "attempt": 1,
307 "uid": "hdishd83djaidwnduwk28bcsb"
308 },
309 "log_directory": "/tmp",
310 "linux": {
311 }
312 }
313 $ crictl runp pod-config.json
315 f84dd361f8dc51518ed291fbadd6db537b0496536c1d2d6c05ff943ce8c9a54f
316 List pod sandboxes and check the sandbox is in Ready state:
320 $ crictl pods
323 POD ID CREATED STATE NAME NAMESPACE ATTEMPT
324 f84dd361f8dc5 17 seconds ago Ready busybox-sandbox default 1
325 Run pod sandbox with runtime handler
329 Runtime handler requires runtime support. The following example shows
330 running a pod sandbox with runsc handler on containerd runtime.
331 $ cat pod-config.json
334 {
335 "metadata": {
336 "name": "nginx-runsc-sandbox",
337 "namespace": "default",
338 "attempt": 1,
339 "uid": "hdishd83djaidwnduwk28bcsb"
340 },
341 "log_directory": "/tmp",
342 "linux": {
343 }
344 }
345 $ crictl runp --runtime=runsc pod-config.json
347 c112976cb6caa43a967293e2c62a2e0d9d8191d5109afef230f403411147548c
348 $ crictl inspectp c112976cb6caa43a967293e2c62a2e0d9d8191d5109afef230f403411147548c
350 "runtime": {
351 "runtimeType": "io.containerd.runtime.v1.linux",
352 "runtimeEngine": "/usr/local/sbin/runsc",
353 "runtimeRoot": "/run/containerd/runsc"
354 },
355 Pull a busybox image
359 $ crictl pull busybox
360 Image is up to date for busybox@sha256:141c253bc4c3fd0a201d32dc1f493bcf3fff003b6df416dea4f41046e0f37d47
361 List images and check the busybox image has been pulled:
365 $ crictl images
368 IMAGE TAG IMAGE ID SIZE
369 busybox latest 8c811b4aec35f 1.15MB
370 k8s.gcr.io/pause 3.1 da86e6ba6ca19 742kB
371 Create container in the pod sandbox with config file
375 $ cat pod-config.json
376 {
377 "metadata": {
378 "name": "nginx-sandbox",
379 "namespace": "default",
380 "attempt": 1,
381 "uid": "hdishd83djaidwnduwk28bcsb"
382 },
383 "log_directory": "/tmp",
384 "linux": {
385 }
386 }
387 $ cat container-config.json
389 {
390 "metadata": {
391 "name": "busybox"
392 },
393 "image":{
394 "image": "busybox"
395 },
396 "command": [
397 "top"
398 ],
399 "log_path":"busybox.0.log",
400 "linux": {
401 }
402 }
403 $ crictl create f84dd361f8dc51518ed291fbadd6db537b0496536c1d2d6c05ff943ce8c9a54f container-config.json pod-config.json
405 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
406 List containers and check the container is in Created state:
410 $ crictl ps -a
413 CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT
414 3e025dd50a72d busybox 32 seconds ago Created busybox 0
415 Start container
419 $ crictl start 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
420 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
421 $ crictl ps
423 CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT
424 3e025dd50a72d busybox About a minute ago Running busybox 0
425 Exec a command in container
429 crictl exec -i -t 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60 ls
430 bin dev etc home proc root sys tmp usr var
431 Create and start a container within one command
435 It is possible to start a container within a single command, whereas
436 the image will be pulled automatically, too:
437 $ cat pod-config.json
440 {
441 "metadata": {
442 "name": "nginx-sandbox",
443 "namespace": "default",
444 "attempt": 1,
445 "uid": "hdishd83djaidwnduwk28bcsb"
446 },
447 "log_directory": "/tmp",
448 "linux": {
449 }
450 }
451 $ cat container-config.json
453 {
454 "metadata": {
455 "name": "busybox"
456 },
457 "image":{
458 "image": "busybox"
459 },
460 "command": [
461 "top"
462 ],
463 "log_path":"busybox.0.log",
464 "linux": {
465 }
466 }
467 $ crictl run container-config.json pod-config.json
469 b25b4f26e342969eb40d05e98130eee0846557d667e93deac992471a3b8f1cf4
470 List containers and check the container is in Running state:
474 $ crictl ps
477 CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID
478 b25b4f26e3429 busybox:latest 14 seconds ago Running busybox 0 158d7a6665ff3
479
483 • See the Kubernetes.io Debugging Kubernetes nodes with crictl
484 doc ⟨https://kubernetes.io/docs/tasks/debug-application-clus‐
485 ter/crictl/⟩
486 • Visit kubernetes-sigs/cri-tools ⟨https://github.com/kuber‐
488 netes-sigs/cri-tools⟩ for more information.
489(CRI) Interface Container(Runtime)