-
Notifications
You must be signed in to change notification settings - Fork 460
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #111 from feiskyer/doc
Add cri-tools docs
- Loading branch information
Showing
5 changed files
with
274 additions
and
150 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| # Container Runtime Interface (CRI) Performance Benchmarking | ||
|
|
||
| CRI performance benchmarking provides a benchmarking framework for CRI-compatible container runtimes. This allows the CRI runtime developers to benchmark the performance of their runtime without needing to set up Kubernetes components or run Kubernetes benchmark tests. | ||
|
|
||
| ## Install | ||
|
|
||
| The benchmarking tests can be installed easily via `go get` command: | ||
|
|
||
| ```sh | ||
| go get github.com/kubernetes-incubator/cri-tools/cmd/critest | ||
| ``` | ||
|
|
||
| Then `critest` binary can be found in `$GOPATH/bin`. | ||
|
|
||
| *Note: ensure GO is installed and GOPATH is set before installing critest.* | ||
|
|
||
| ## Running tests | ||
|
|
||
| ### Prerequisite | ||
|
|
||
| Before running the test, you need to _ensure that the CRI server under test is running and listening on a Unix socket_. Because the benchmark tests are designed to request changes (e.g., create/delete) to the containers and verify that correct status is reported, it expects to be the only user of the CRI server. Please make sure that 1) there are no existing CRI-managed containers running on the node, and 2) no other processes (e.g., Kubelet) will interfere with the tests. | ||
|
|
||
| ### Run | ||
|
|
||
| ```sh | ||
| critest benchmark | ||
| ``` | ||
|
|
||
| This will | ||
|
|
||
| - Connect to the shim of CRI container runtime | ||
| - Run the benchmark tests using `ginkgo` | ||
| - Output the test results to STDOUT | ||
|
|
||
| critest connects to `/var/run/dockershim.sock` by default. For other runtimes, the endpoint can be set in two ways: | ||
|
|
||
| - By setting flags `--runtime-endpoint` and `--image-endpoint` | ||
| - By setting environment variables `CRI_RUNTIME_ENDPOINT` and `CRI_IMAGE_ENDPOINT` | ||
|
|
||
| ## Additional options | ||
|
|
||
| - `--focus`, `-f`: Only run the tests that match the regular expression. | ||
| - -`-ginkgo-flags`, `-g`: Space-separated list of arguments to pass to Ginkgo test runner. | ||
| - `--image-endpoint`, `-i`: Set the endpoint of image service. Same with runtime-endpoint if not specified. | ||
| - `--runtime-endpoint`, `-r`: Set the endpoint of runtime service. Default to `/var/run/dockershim.sock`. | ||
| - `--skip`, `-s`: Skip the tests that match the regular expression. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| # Container Runtime Interface (CRI) CLI | ||
|
|
||
| crictl provides a CLI for CRI-compatible container runtimes. This allows the CRI runtime developers to debug of their runtime without needing to set up Kubernetes components. | ||
|
|
||
| crictl is currently Alpha and still under quick iterations. We encourage the CRI developers to report bugs or help extend the coverage by adding more functionalities. | ||
|
|
||
| ## Install | ||
|
|
||
| The CRI CLI can be installed easily via `go get` command: | ||
|
|
||
| ```sh | ||
| go get github.com/kubernetes-incubator/cri-tools/cmd/crictl | ||
| ``` | ||
|
|
||
| Then `crictl` binary can be found in `$GOPATH/bin`. | ||
|
|
||
| *Note: ensure GO is installed and GOPATH is set before installing crictl.* | ||
|
|
||
| ## Usage | ||
|
|
||
| ```sh | ||
| crictl SUBCOMMAND [FLAGS] | ||
| ``` | ||
|
|
||
| Subcommands includes: | ||
|
|
||
| - `info`: Get version information of runtime | ||
| - `sandbox`, `sb`: Manage lifecycle of podsandbox | ||
| - `container`, `ctr`: Manage lifecycle of container | ||
| - `status`: Get the status information of runtime | ||
| - `attach`: Attach a running container | ||
| - `image`: Manage images | ||
| - `exec`: Exec(exec, syncexec) a command in a running container | ||
| - `portforward`: Forword ports(localport:remoteport) from a sandbox | ||
| - `help`, `h`: Shows a list of commands or help for one command | ||
|
|
||
| crictl connects to `/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 `CRI_RUNTIME_ENDPOINT` and `CRI_IMAGE_ENDPOINT` | ||
| - By setting the endpoint in the config file `--config-file=/etc/crictl.yaml` | ||
|
|
||
| ``` | ||
| # cat /etc/crictl.yaml | ||
| runtime-endpoint: /var/run/dockershim.sock | ||
| image-endpoint: /var/run/dockershim.sock | ||
| timeout: 10 | ||
| debug: true | ||
| ``` | ||
|
|
||
| ## Additional options | ||
|
|
||
| - `--runtime-endpoint`: CRI server runtime endpoint (default: "/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`: CRI server image endpoint, default same as runtime endpoint. | ||
| - `--timeout`: Timeout of connecting to server (default: 10s) | ||
| - `--debug`: Enable debug output | ||
| - `--help`, `-h`: show help | ||
| - `--version`, `-v`: print the version information of crictl | ||
| - `--config-file`: Config file in yaml format. Overrided by flags or environment variables. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Run sandbox with config file | ||
|
|
||
| ``` | ||
| # cat sandbox-config.json | ||
| { | ||
| "metadata": { | ||
| "name": "nginx-sandbox", | ||
| "namespace": "default", | ||
| "attempt": 1, | ||
| "uid": "hdishd83djaidwnduwk28bcsb" | ||
| }, | ||
| "linux": { | ||
| } | ||
| } | ||
| # crictl sandbox run sandbox-config.json | ||
| 9b542bfe8f93eb2d726d0f7b619f253c18858006aa53023e392e138b0be6301c | ||
| ``` | ||
|
|
||
| ### Create container in a sandbox with config file | ||
|
|
||
| ``` | ||
| # 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 container create 9b542bfe8f93eb2d726d0f7b619f253c18858006aa53023e392e138b0be6301c container-config.json sandbox-config.json | ||
| bf642f55ecf54345354a86a42c08fb0d66e55e90c855973495f31e991c2bf725 | ||
| ``` | ||
|
|
||
| ### Start container | ||
|
|
||
| ``` | ||
| # crictl container start bf642f55ecf54345354a86a42c08fb0d66e55e90c855973495f31e991c2bf725 | ||
| bf642f55ecf54345354a86a42c08fb0d66e55e90c855973495f31e991c2bf725 | ||
| ``` | ||
|
|
||
| ### Exec a command in container | ||
|
|
||
| ``` | ||
| # crictl exec -i -t bf642f55ecf54345354a86a42c08fb0d66e55e90c855973495f31e991c2bf725 sh | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # ROADMAP | ||
|
|
||
| CRI tools is a set of tools for Kubelet Container Runtime Interface (CRI). It is | ||
|
|
||
| - designing for all CRI-compatible container runtimes. | ||
| - aiming to help runtime maintainers for validation and debugging | ||
| - portable and easy to use | ||
|
|
||
| ## Components | ||
|
|
||
| CRI tools is composed of two components: | ||
|
|
||
| - critest: validation and performance benchmark test suites | ||
| - crictl: CLI for Kubelet CRI | ||
|
|
||
| ## Roadmap | ||
|
|
||
| ### Kubernetes v1.7 | ||
|
|
||
| - CRI validation test suites | ||
| - Basic sandbox/container operations | ||
| - Basic image operations | ||
| - networking | ||
| - DNS config | ||
| - port mapping | ||
| - streaming | ||
| - exec, attach, portforward | ||
| - security context | ||
| - hostPID, hostIPC, hostNetwork | ||
| - runAsUser, readOnlyRootfs, privileged | ||
| - execSync | ||
| - version | ||
| - status | ||
|
|
||
| ### Kubernetes v1.8 | ||
|
|
||
| - Supporting TLS for streaming operations | ||
| - Validation test suites for experimental features, e.g. SELinux, Apparmor, Seccomp, Devices, Resource Limits | ||
| - Benchmark test suites, e.g. | ||
| - Latency | ||
| - resource usage (CPU, memory, disk IO, network IO) | ||
| - UX improvin, e.g. | ||
| - support more output formats: -o json|yaml | ||
| - Debugging |
Oops, something went wrong.