diff --git a/README.md b/README.md index 20c572ade..d9f42c5b3 100644 --- a/README.md +++ b/README.md @@ -105,6 +105,9 @@ CONTAINER_RUNTIME=remote CONTAINER_RUNTIME_ENDPOINT='/var/run/cri-containerd.soc ``` ### Test See [here](./docs/testing.md) for information about test. +## Using crictl +See [here](./docs/crictl.md) for information about using `crictl` to debug +pods, containers, and images. ## Documentation See [here](./docs) for additional documentation. ## Contributing diff --git a/docs/crictl.md b/docs/crictl.md new file mode 100644 index 000000000..f20d115de --- /dev/null +++ b/docs/crictl.md @@ -0,0 +1,173 @@ +CRICTL User Guide +================= +This document presumes you already have `containerd` and `cri-containerd` +installed and running. + +This document is for developers who wish to debug, inspect, and manage their pods, +containers, and container images. + +Before generating issues against this document, `containerd`, `cri-containerd`, +or `crictl` please make sure the issue has not already been submitted. + +## Install crictl +If you have not already installed crictl please install the version compatible +with the `cri-containerd` you are using. If you are a user, your deployment +should have installed crictl for you. If not, get it from your release tarball. +If you are a developer the current version of crictl is specified [here](./hack/version). +A helper command has been included to install the dependencies at the right version: +```console +$ make install.deps +``` +* Note: The file named `/etc/crictl.yaml` is used to configure crictl +so you don't have to repeatedly specify the runtime sock used to connect crictl +to the container runtime: +```console +$ cat /etc/crictl.yaml +runtime-endpoint: /run/containerd/containerd.sock +image-endpoint: /run/containerd/containerd.sock +timeout: 10 +debug: true +``` + +## Download and Inspect a Container Image +```console +$ crictl pull busybox + ... +$ crictl inspecti busybox + ... displays information about the image. +``` +## Run a pod sandbox (using a config file) +```console +$ cat sandbox-config.json +{ + "metadata": { + "name": "nginx-sandbox", + "namespace": "default", + "attempt": 1, + "uid": "hdishd83djaidwnduwk28bcsb" + }, + "linux": { + } +} + +$ crictl runs sandbox-config.json +e1c83b0b8d481d4af8ba98d5f7812577fc175a37b10dc824335951f52addbb4e +$ crictl sandboxes +SANDBOX ID CREATED STATE NAME NAMESPACE ATTEMPT +e1c83b0b8d481 2 hours ago SANDBOX_READY nginx-sandbox default 1 +$ crictl inspects e1c8 + ... displays information about the pod and the sandbox pause container. +``` +* Note: As shown above, you may use truncated IDs if they are unique. +* Other commands to manage the pod include `stops ID` to stop a running pod and +`rms ID` to remove a pod sandbox. + +## Create and Run a Container in a Sandbox (using a config file) +```console +$ cat sandbox-config.json +{ + "metadata": { + "name": "nginx-sandbox", + "namespace": "default", + "attempt": 1, + "uid": "hdishd83djaidwnduwk28bcsb" + }, + "linux": { + } +} + +$ cat container-config.json +{ + "metadata": { + "name": "busybox" + }, + "image":{ + "image": "busybox" + }, + "command": [ + "top" + ], + "linux": { + } +} + +$ crictl create e1c83 container-config.json sandbox-config.json +0a2c761303163f2acaaeaee07d2ba143ee4cea7e3bde3d32190e2a36525c8a05 +$ crictl ps +CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT +0a2c761303163 docker.io/busybox 2 hours ago CONTAINER_CREATED busybox 0 +$ crictl start 0a2c +0a2c761303163f2acaaeaee07d2ba143ee4cea7e3bde3d32190e2a36525c8a05 +$ crictl ps +CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT +0a2c761303163 docker.io/busybox 2 hours ago CONTAINER_RUNNING busybox 0 +$ crictl inspect 0a2c7 + ... show detailed information about the container +``` +## Exec a Command in the Container +```console +$ crictl exec -i -t 0a2c ls +bin dev etc home proc root sys tmp usr var +``` +## Display Stats for the Container +```console +$ crictl stats +CONTAINER CPU % MEM DISK INODES +0a2c761303163f 0.00 991.2kB 16.38kB 6 +``` +* Other commands to manage the container include `stop ID` to stop a running +container and `rm ID` to remove a container. +## Display Version Information +```console +$ crictl version +Version: 0.1.0 +RuntimeName: cri-containerd +RuntimeVersion: 1.0.0-alpha.1-167-g737efe7-dirty +RuntimeApiVersion: 0.0.0 +``` +## Display Status & Configuration Information about Containerd & CRI-Containerd +```console +$ crictl info +{ + "status": { + "conditions": [ + { + "type": "RuntimeReady", + "status": true, + "reason": "", + "message": "" + }, + { + "type": "NetworkReady", + "status": true, + "reason": "", + "message": "" + } + ] + }, + "config": { + "containerd": { + "rootDir": "/var/lib/containerd", + "snapshotter": "overlayfs", + "endpoint": "/run/containerd/containerd.sock", + "runtime": "io.containerd.runtime.v1.linux" + }, + "cni": { + "binDir": "/opt/cni/bin", + "confDir": "/etc/cni/net.d" + }, + "socketPath": "/var/run/cri-containerd.sock", + "rootDir": "/var/lib/cri-containerd", + "streamServerPort": "10010", + "sandboxImage": "gcr.io/google_containers/pause:3.0", + "statsCollectPeriod": 10, + "oomScore": -999, + "enableProfiling": true, + "profilingPort": "10011", + "profilingAddress": "127.0.0.1" + } +} +``` +## More Information +See [here](https://github.com/kubernetes-incubator/cri-tools/blob/master/docs/crictl.md) +for information about crictl.