From 997f1f6cd0c115aec0bf9a97c736bd3d8e7da3f0 Mon Sep 17 00:00:00 2001 From: bin liu Date: Fri, 9 Oct 2020 14:22:57 +0800 Subject: [PATCH] docs: Add crictl example json files Add basic sample pod/container config files to show how to use `crictl` with Kata containers. Fixes: #881 Signed-off-by: bin liu --- docs/how-to/README.md | 1 + .../data/crictl/busybox/container_config.json | 18 +++ .../data/crictl/busybox/sandbox_config.json | 19 +++ .../redis/redis_client_container_config.json | 38 +++++ .../redis/redis_client_sandbox_config.json | 27 ++++ .../redis/redis_server_container_config.json | 35 ++++ .../redis/redis_server_sandbox_config.json | 27 ++++ docs/how-to/run-kata-with-crictl.md | 150 ++++++++++++++++++ 8 files changed, 315 insertions(+) create mode 100644 docs/how-to/data/crictl/busybox/container_config.json create mode 100644 docs/how-to/data/crictl/busybox/sandbox_config.json create mode 100644 docs/how-to/data/crictl/redis/redis_client_container_config.json create mode 100644 docs/how-to/data/crictl/redis/redis_client_sandbox_config.json create mode 100644 docs/how-to/data/crictl/redis/redis_server_container_config.json create mode 100644 docs/how-to/data/crictl/redis/redis_server_sandbox_config.json create mode 100644 docs/how-to/run-kata-with-crictl.md diff --git a/docs/how-to/README.md b/docs/how-to/README.md index 2aaec04356..79f57966f4 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -6,6 +6,7 @@ * [Advanced Topics](#advanced-topics) ## Kubernetes Integration +- [Run Kata containers with `crictl`](run-kata-with-crictl.md) - [Run Kata Containers with Kubernetes](run-kata-with-k8s.md) - [How to use Kata Containers and Containerd](containerd-kata.md) - [How to use Kata Containers and CRI (containerd plugin) with Kubernetes](how-to-use-k8s-with-cri-containerd-and-kata.md) diff --git a/docs/how-to/data/crictl/busybox/container_config.json b/docs/how-to/data/crictl/busybox/container_config.json new file mode 100644 index 0000000000..5772496514 --- /dev/null +++ b/docs/how-to/data/crictl/busybox/container_config.json @@ -0,0 +1,18 @@ +{ + "metadata": { + "name": "busybox-container" + }, + "image": { + "image": "docker.io/library/busybox:latest" + }, + "command": [ + "sleep", + "9999" + ], + "args": [], + "working_dir": "/", + "log_path": "", + "stdin": false, + "stdin_once": false, + "tty": false +} diff --git a/docs/how-to/data/crictl/busybox/sandbox_config.json b/docs/how-to/data/crictl/busybox/sandbox_config.json new file mode 100644 index 0000000000..963db8633c --- /dev/null +++ b/docs/how-to/data/crictl/busybox/sandbox_config.json @@ -0,0 +1,19 @@ +{ + "metadata": { + "name": "busybox-pod", + "uid": "busybox-pod" + }, + "hostname": "busybox_host", + "log_directory": "", + "dns_config": { + }, + "port_mappings": [], + "resources": { + }, + "labels": { + }, + "annotations": { + }, + "linux": { + } +} diff --git a/docs/how-to/data/crictl/redis/redis_client_container_config.json b/docs/how-to/data/crictl/redis/redis_client_container_config.json new file mode 100644 index 0000000000..95c42248ec --- /dev/null +++ b/docs/how-to/data/crictl/redis/redis_client_container_config.json @@ -0,0 +1,38 @@ +{ + "metadata": { + "name": "redis-client" + }, + "image": { + "image": "docker.io/library/redis:6.0.8-alpine" + }, + "command": [ + "tail", "-f", "/dev/null" + ], + "envs": [ + { + "key": "PATH", + "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + }, + { + "key": "TERM", + "value": "xterm" + } + ], + "labels": { + "tier": "backend" + }, + "annotations": { + "pod": "redis-client-pod" + }, + "log_path": "", + "stdin": false, + "stdin_once": false, + "tty": false, + "linux": { + "resources": { + "memory_limit_in_bytes": 524288000 + }, + "security_context": { + } + } +} diff --git a/docs/how-to/data/crictl/redis/redis_client_sandbox_config.json b/docs/how-to/data/crictl/redis/redis_client_sandbox_config.json new file mode 100644 index 0000000000..6613d3c0d9 --- /dev/null +++ b/docs/how-to/data/crictl/redis/redis_client_sandbox_config.json @@ -0,0 +1,27 @@ +{ + "metadata": { + "name": "redis-client-pod", + "uid": "test-redis-client-pod" + }, + "hostname": "redis-client", + "log_directory": "", + "dns_config": { + "searches": [ + "8.8.8.8" + ] + }, + "port_mappings": [], + "resources": { + "cpu": { + "limits": 1, + "requests": 1 + } + }, + "labels": { + "tier": "backend" + }, + "annotations": { + }, + "linux": { + } +} diff --git a/docs/how-to/data/crictl/redis/redis_server_container_config.json b/docs/how-to/data/crictl/redis/redis_server_container_config.json new file mode 100644 index 0000000000..faf1f444d0 --- /dev/null +++ b/docs/how-to/data/crictl/redis/redis_server_container_config.json @@ -0,0 +1,35 @@ +{ + "metadata": { + "name": "redis-server" + }, + "image": { + "image": "docker.io/library/redis:6.0.8-alpine" + }, + "envs": [ + { + "key": "PATH", + "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" + }, + { + "key": "TERM", + "value": "xterm" + } + ], + "labels": { + "tier": "backend" + }, + "annotations": { + "pod": "redis-server-pod" + }, + "log_path": "", + "stdin": false, + "stdin_once": false, + "tty": false, + "linux": { + "resources": { + "memory_limit_in_bytes": 524288000 + }, + "security_context": { + } + } +} diff --git a/docs/how-to/data/crictl/redis/redis_server_sandbox_config.json b/docs/how-to/data/crictl/redis/redis_server_sandbox_config.json new file mode 100644 index 0000000000..29af2d133d --- /dev/null +++ b/docs/how-to/data/crictl/redis/redis_server_sandbox_config.json @@ -0,0 +1,27 @@ +{ + "metadata": { + "name": "redis-server-pod", + "uid": "test-redis-server-pod" + }, + "hostname": "redis-server", + "log_directory": "", + "dns_config": { + "searches": [ + "8.8.8.8" + ] + }, + "port_mappings": [], + "resources": { + "cpu": { + "limits": 1, + "requests": 1 + } + }, + "labels": { + "tier": "backend" + }, + "annotations": { + }, + "linux": { + } +} diff --git a/docs/how-to/run-kata-with-crictl.md b/docs/how-to/run-kata-with-crictl.md new file mode 100644 index 0000000000..b7c1b19886 --- /dev/null +++ b/docs/how-to/run-kata-with-crictl.md @@ -0,0 +1,150 @@ +# Working with `crictl` + +* [What's `cri-tools`](#whats-cri-tools) +* [Use `crictl` run Pods in Kata containers](#use-crictl-run-pods-in-kata-containers) + * [Run `busybox` Pod](#run-busybox-pod) + * [Run pod sandbox with config file](#run-pod-sandbox-with-config-file) + * [Create container in the pod sandbox with config file](#create-container-in-the-pod-sandbox-with-config-file) + * [Start container](#start-container) + * [Run `redis` Pod](#run-redis-pod) + * [Create `redis-server` Pod](#create-redis-server-pod) + * [Create `redis-client` Pod](#create-redis-client-pod) + * [Check `redis` server is working](#check-redis-server-is-working) + +## What's `cri-tools` + +[`cri-tools`](https://github.com/kubernetes-sigs/cri-tools) provides debugging and validation tools for Kubelet Container Runtime Interface (CRI). + +`cri-tools` includes two tools: `crictl` and `critest`. `crictl` is the CLI for Kubelet CRI, in this document, we will show how to use `crictl` to run Pods in Kata containers. + +> **Note:** `cri-tools` is only used for debugging and validation purpose, and don't use it to run production workloads. + +> **Note:** For how to install and configure `cri-tools` with CRI runtimes like `containerd` or CRI-O, please also refer to other [howtos](./README.md). + +## Use `crictl` run Pods in Kata containers + +Sample config files in this document can be found [here](./data/crictl/). + +### Run `busybox` Pod + +#### Run pod sandbox with config file + +```bash +$ sudo crictl runp -r kata sandbox_config.json +16a62b035940f9c7d79fd53e93902d15ad21f7f9b3735f1ac9f51d16539b836b + +$ sudo crictl pods +POD ID CREATED STATE NAME NAMESPACE ATTEMPT +16a62b035940f 21 seconds ago Ready busybox-pod 0 +``` + +#### Create container in the pod sandbox with config file + +```bash +$ sudo crictl create 16a62b035940f container_config.json sandbox_config.json +e6ca0e0f7f532686236b8b1f549e4878e4fe32ea6b599a5d684faf168b429202 +``` + +List containers and check the container is in `Created` state: + +```bash +$ sudo crictl ps -a +CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID +e6ca0e0f7f532 docker.io/library/busybox:latest 19 seconds ago Created busybox-container 0 16a62b035940f +``` + +#### Start container + +```bash +$ sudo crictl start e6ca0e0f7f532 +e6ca0e0f7f532 +``` + +List containers and we can see that the container state has changed from `Created` to `Running`: + +```bash +$ sudo crictl ps +CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID +e6ca0e0f7f532 docker.io/library/busybox:latest About a minute ago Running busybox-container 0 16a62b035940f +``` + +And last we can `exec` into `busybox` container: + +```bash +$ sudo crictl exec -it e6ca0e0f7f532 sh +``` + +And run commands in it: + +``` +/ # hostname +busybox_host +/ # id +uid=0(root) gid=0(root) +``` + +### Run `redis` Pod + +In this example, we will create two Pods: one is for `redis` server, and another one is `redis` client. + +#### Create `redis-server` Pod + +It's also possible to start a container within a single command: + +```bash +$ sudo crictl run -r kata redis_server_container_config.json redis_server_sandbox_config.json +bb36e05c599125842c5193909c4de186b1cee3818f5d17b951b6a0422681ce4b +``` + +#### Create `redis-client` Pod + +```bash +$ sudo crictl run -r kata redis_client_container_config.json redis_client_sandbox_config.json +e344346c5414e3f51f97f20b2262e0b7afe457750e94dc0edb109b94622fc693 +``` + +After the new container started, we can check the running Pods and containers. + +```bash +$ sudo crictl pods +POD ID CREATED STATE NAME NAMESPACE ATTEMPT +469d08a7950e3 30 seconds ago Ready redis-client-pod 0 +02c12fdb08219 About a minute ago Ready redis-server-pod 0 + +$ sudo crictl ps +CONTAINER IMAGE CREATED STATE NAME ATTEMPT POD ID +e344346c5414e docker.io/library/redis:6.0.8-alpine 35 seconds ago Running redis-client 0 469d08a7950e3 +bb36e05c59912 docker.io/library/redis:6.0.8-alpine About a minute ago Running redis-server 0 02c12fdb08219 +``` + +#### Check `redis` server is working + +To connect to the `redis-server`. First we need to get the `redis-server`'s IP address. + +```bash + +$ server=$(sudo crictl inspectp 02c12fdb08219 | jq .status.network.ip | tr -d '"' ) +$ echo $server +172.19.0.118 +``` + +Launch `redis-cli` in the new Pod and connect server running at `172.19.0.118`. + +```bash +$ sudo crictl exec -it e344346c5414e redis-cli -h $server +172.19.0.118:6379> get test-key +(nil) +172.19.0.118:6379> set test-key test-value +OK +172.19.0.118:6379> get test-key +"test-value" +``` + +Then back to `redis-server`, check if the `test-key` is set in server. + +```bash +$ sudo crictl exec -it bb36e05c59912 redis-cli get test-key +"test-val" +``` + +Returned `test-val` is just set by `redis-cli` in `redis-client` Pod.