Add documentation for crictl

kubernetes · Jun 5, 2018 · 57b473e · 57b473e
1 parent ef11602
commit 57b473e
Show file tree

Hide file tree

Showing 2 changed files with 196 additions and 2 deletions.
diff --git a/content/en/docs/tasks/debug-application-cluster/crictl.md b/content/en/docs/tasks/debug-application-cluster/crictl.md
@@ -0,0 +1,195 @@
+---
+reviewers:
+- Random-Liu
+- feiskyer
+- mrunalp
+title: Crictl
+---
+
+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 GA since v1.11.0 and is hosted at the [cri-tools](https://github.com/kubernetes-incubator/cri-tools) repository. We encourage the CRI developers to report bugs or help extend the coverage by adding more functionalities.
+
+{{< toc >}}
+
+## Install crictl
+
+crictl can be downloaded from cri-tools [release page](https://github.com/kubernetes-incubator/cri-tools/releases):
+
+```sh
+VERSION="v1.11.0"
+wget https://github.com/kubernetes-incubator/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
+```
+
+## Usage
+
+```sh
+crictl SUBCOMMAND [FLAGS]
+```
+
+Subcommands includes:
+
+- `attach`:       Attach to a running container
+- `create`:       Create a new container
+- `exec`:         Run a command in a running container
+- `version`:      Display runtime version information
+- `images`:       List images
+- `inspect`:      Display the status of one or more containers
+- `inspecti`:     Return the status of one ore more images
+- `inspectp`:     Display the status of one or more pods
+- `logs`:         Fetch the logs of a container
+- `port-forward`: Forward local port to a pod
+- `ps`:           List containers
+- `pull`:         Pull an image from a registry
+- `runp`:         Run a new pod
+- `rm`:           Remove one or more containers
+- `rmi`:          Remove one or more images
+- `rmp`:          Remove one or more pods
+- `pods`:         List pods
+- `start`:        Start one or more created containers
+- `info`:         Display information of the container runtime
+- `stop`:         Stop one or more running containers
+- `stopp`:        Stop one or more running pods
+- `update`:       Update one or more running containers
+- `config`:       Get and set crictl options
+- `stats`:        List container(s) resource usage statistics
+- `completion`:   Output bash shell completion code
+- `help, h`:      Shows a list of commands or help for one command
+
+crictl connects to `unix:///var/run/dockershim.sock` by default. For other runtimes, the endpoint can be set in three ways:
+
+- By setting flags `--runtime-endpoint` and `--image-endpoint`
+- By setting environment variables `CONTAINER_RUNTIME_ENDPOINT` and `IMAGE_SERVICE_ENDPOINT`
+- By setting the endpoint in the config file `--config=/etc/crictl.yaml`
+
+```sh
+$ cat /etc/crictl.yaml
+runtime-endpoint: unix:///var/run/dockershim.sock
+image-endpoint: unix:///var/run/dockershim.sock
+timeout: 10
+debug: true
+```
+
+## Additional options
+
+- `--runtime-endpoint`, `-r`: CRI server runtime endpoint (default: "unix:///var/run/dockershim.sock").The default server is dockershim. If we want to debug other CRI server such as frakti, we can add flag `--runtime-endpoint=/var/run/frakti.sock`
+- `--image-endpoint`, `-i`: CRI server image endpoint, default same as runtime endpoint.
+- `--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.
+
+## Examples
+
+### Run pod sandbox with config file
+
+```sh
+$ cat pod-config.json
+{
+    "metadata": {
+        "name": "nginx-sandbox",
+        "namespace": "default",
+        "attempt": 1,
+        "uid": "hdishd83djaidwnduwk28bcsb"
+    },
+    "logDirectory": "/tmp",
+    "linux": {
+    }
+}
+
+$ crictl runp pod-config.json
+f84dd361f8dc51518ed291fbadd6db537b0496536c1d2d6c05ff943ce8c9a54f
+```
+
+List pod sandboxes and check the sandbox is in Ready state:
+
+```sh
+$ crictl pods
+POD ID              CREATED             STATE               NAME                NAMESPACE           ATTEMPT
+f84dd361f8dc5       17 seconds ago      Ready               busybox-sandbox     default             1
+```
+
+### Pull a busybox image
+
+```sh
+$ crictl pull busybox
+Image is up to date for busybox@sha256:141c253bc4c3fd0a201d32dc1f493bcf3fff003b6df416dea4f41046e0f37d47
+```
+
+List images and check the busybox image has been pulled:
+
+```sh
+$ crictl images
+IMAGE               TAG                 IMAGE ID            SIZE
+busybox             latest              8c811b4aec35f       1.15MB
+k8s.gcr.io/pause    3.1                 da86e6ba6ca19       742kB
+```
+
+### Create container in the pod sandbox with config file
+
+```sh
+$ 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:
+
+```sh
+$ crictl ps -a
+CONTAINER ID        IMAGE               CREATED             STATE               NAME                ATTEMPT
+3e025dd50a72d       busybox             32 seconds ago      Created             busybox             0
+```
+
+### Start container
+
+```sh
+$ crictl start 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
+3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60
+
+$ crictl ps
+CONTAINER ID        IMAGE               CREATED              STATE               NAME                ATTEMPT
+3e025dd50a72d       busybox             About a minute ago   Running             busybox             0
+```
+
+### Exec a command in container
+
+```sh
+crictl exec -i -t 3e025dd50a72d956c4f14881fbb5b1080c9275674e95fb67f965f6478a957d60 ls
+bin   dev   etc   home  proc  root  sys   tmp   usr   var
+```
+
+## More information
+
+Visit [kubernetes-incubator/cri-tools](https://github.com/kubernetes-incubator/cri-tools) for more information.
diff --git a/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md b/content/en/docs/tasks/debug-application-cluster/debug-application-introspection.md
@@ -359,5 +359,4 @@ Learn about additional debugging tools, including:
 * [Getting into containers via `exec`](/docs/tasks/debug-application-cluster/get-shell-running-container/)
 * [Connecting to containers via proxies](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
 * [Connecting to containers via port forwarding](/docs/tasks/access-application-cluster/port-forward-access-application-cluster/)
-
-
+* [Crictl](/docs/tasks/debug-application-cluster/crictl/)