diff options
Diffstat (limited to 'g3doc/user_guide/containerd')
| -rw-r--r-- | g3doc/user_guide/containerd/BUILD | 33 | ||||
| -rw-r--r-- | g3doc/user_guide/containerd/configuration.md | 96 | ||||
| -rw-r--r-- | g3doc/user_guide/containerd/containerd_11.md | 167 | ||||
| -rw-r--r-- | g3doc/user_guide/containerd/quick_start.md | 180 |
4 files changed, 0 insertions, 476 deletions
diff --git a/g3doc/user_guide/containerd/BUILD b/g3doc/user_guide/containerd/BUILD deleted file mode 100644 index 0ede4819c..000000000 --- a/g3doc/user_guide/containerd/BUILD +++ /dev/null @@ -1,33 +0,0 @@ -load("//website:defs.bzl", "doc") - -package( - default_visibility = ["//website:__pkg__"], - licenses = ["notice"], -) - -doc( - name = "quick_start", - src = "quick_start.md", - category = "User Guide", - permalink = "/docs/user_guide/containerd/quick_start/", - subcategory = "Containerd", - weight = "10", -) - -doc( - name = "configuration", - src = "configuration.md", - category = "User Guide", - permalink = "/docs/user_guide/containerd/configuration/", - subcategory = "Containerd", - weight = "90", -) - -doc( - name = "containerd_11", - src = "containerd_11.md", - category = "User Guide", - include_in_menu = False, - permalink = "/docs/user_guide/containerd/containerd_11/", - subcategory = "Containerd", -) diff --git a/g3doc/user_guide/containerd/configuration.md b/g3doc/user_guide/containerd/configuration.md deleted file mode 100644 index 011af3b10..000000000 --- a/g3doc/user_guide/containerd/configuration.md +++ /dev/null @@ -1,96 +0,0 @@ -# Containerd Advanced Configuration - -This document describes how to configure runtime options for -`containerd-shim-runsc-v1`. You can find the installation instructions and -minimal requirements in [Containerd Quick Start](./quick_start.md). - -## Shim Configuration - -The shim can be provided with a configuration file containing options to the -shim itself as well as a set of flags to runsc. Here is a quick example: - -```shell -cat <<EOF | sudo tee /etc/containerd/runsc.toml -option = "value" -[runsc_config] - flag = "value" -``` - -The set of options that can be configured can be found in -[options.go](https://cs.opensource.google/gvisor/gvisor/+/master:pkg/shim/options.go). -Values under `[runsc_config]` can be used to set arbitrary flags to runsc. -`flag = "value"` is converted to `--flag="value"` when runsc is invoked. Run -`runsc flags` so see which flags are available - -Next, containerd needs to be configured to send the configuration file to the -shim. - -### Containerd 1.3+ - -Starting in 1.3, containerd supports a configurable `ConfigPath` in the runtime -configuration. Here is an example: - -```shell -cat <<EOF | sudo tee /etc/containerd/config.toml -disabled_plugins = ["restart"] -[plugins.cri.containerd.runtimes.runsc] - runtime_type = "io.containerd.runsc.v1" -[plugins.cri.containerd.runtimes.runsc.options] - TypeUrl = "io.containerd.runsc.v1.options" - ConfigPath = "/etc/containerd/runsc.toml" -EOF -``` - -When you are done, restart containerd to pick up the changes. - -```shell -sudo systemctl restart containerd -``` - -## Debug - -When `shim_debug` is enabled in `/etc/containerd/config.toml`, containerd will -forward shim logs to its own log. You can additionally set `level = "debug"` to -enable debug logs. To see the logs run `sudo journalctl -u containerd`. Here is -a containerd configuration file that enables both options: - -```shell -cat <<EOF | sudo tee /etc/containerd/config.toml -disabled_plugins = ["restart"] -[debug] - level = "debug" -[plugins.linux] - shim_debug = true -[plugins.cri.containerd.runtimes.runsc] - runtime_type = "io.containerd.runsc.v1" -[plugins.cri.containerd.runtimes.runsc.options] - TypeUrl = "io.containerd.runsc.v1.options" - ConfigPath = "/etc/containerd/runsc.toml" -EOF -``` - -It can be hard to separate containerd messages from the shim's though. To create -a log file dedicated to the shim, you can set the `log_path` and `log_level` -values in the shim configuration file: - -- `log_path` is the directory where the shim logs will be created. `%ID%` is - the path is replaced with the container ID. -- `log_level` sets the logs level. It is normally set to "debug" as there is - not much interesting happening with other log levels. - -### Example: Enable shim and gVisor debug logging - -gVisor debug logging can be enabled by setting the `debug` and `debug-log` flag. -The shim will replace "%ID%" with the container ID, and "%COMMAND%" with the -runsc command (run, boot, etc.) in the path of the `debug-log` flag. - -Find out more about debugging in the [debugging guide](../debugging.md). - -```shell -cat <<EOF | sudo tee /etc/containerd/runsc.toml -log_path = "/var/log/runsc/%ID%/shim.log" -log_level = "debug" -[runsc_config] - debug = "true" - debug-log = "/var/log/runsc/%ID%/gvisor.%COMMAND%.log" -``` diff --git a/g3doc/user_guide/containerd/containerd_11.md b/g3doc/user_guide/containerd/containerd_11.md deleted file mode 100644 index 200d3da76..000000000 --- a/g3doc/user_guide/containerd/containerd_11.md +++ /dev/null @@ -1,167 +0,0 @@ -# Older Versions (containerd 1.1) - -**WARNING: containerd 1.1 and shim v1 is no longer supported. The instructions -below is kept just for reference in case you're dealing with an old version. -It's highly recommended upgrading to the latest version.** - -This document describes how to install and run the `gvisor-containerd-shim` -using the untrusted workload CRI extension. This requires `containerd` 1.1 or -later. - -*Note: The untrusted workload CRI extension is deprecated by containerd and -`gvisor-containerd-shim` is maintained on a best-effort basis. If you are using -containerd 1.2+, please see the -[containerd 1.2+ documentation](./quick_start.md) and use -`containerd-shim-runsc-v1`.* - -## Requirements - -- **runsc** and **gvisor-containerd-shim**: See the - [installation guide](/docs/user_guide/install/). -- **containerd**: See the [containerd website](https://containerd.io/) for - information on how to install containerd. - -## Configure containerd - -Create the configuration for the gvisor shim in -`/etc/containerd/gvisor-containerd-shim.toml`: - -```shell -cat <<EOF | sudo tee /etc/containerd/gvisor-containerd-shim.toml -# This is the path to the default runc containerd-shim. -runc_shim = "/usr/local/bin/containerd-shim" -EOF -``` - -Update `/etc/containerd/config.toml`. Be sure to update the path to -`gvisor-containerd-shim` and `runsc` if necessary: - -```shell -cat <<EOF | sudo tee /etc/containerd/config.toml -disabled_plugins = ["restart"] -[plugins.linux] - shim = "/usr/local/bin/gvisor-containerd-shim" - shim_debug = true -[plugins.cri.containerd.untrusted_workload_runtime] - runtime_type = "io.containerd.runtime.v1.linux" - runtime_engine = "/usr/local/bin/runsc" - runtime_root = "/run/containerd/runsc" -EOF -``` - -Restart `containerd`: - -```shell -sudo systemctl restart containerd -``` - -## Usage - -You can run containers in gVisor via containerd's CRI. - -### Install crictl - -Download and install the `crictl` binary: - -```shell -{ -wget https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.13.0/crictl-v1.13.0-linux-amd64.tar.gz -tar xf crictl-v1.13.0-linux-amd64.tar.gz -sudo mv crictl /usr/local/bin -} -``` - -Write the `crictl` configuration file: - -```shell -cat <<EOF | sudo tee /etc/crictl.yaml -runtime-endpoint: unix:///run/containerd/containerd.sock -EOF -``` - -### Create the nginx Sandbox in gVisor - -Pull the nginx image: - -```shell -sudo crictl pull nginx -``` - -Create the sandbox creation request: - -```shell -cat <<EOF | tee sandbox.json -{ - "metadata": { - "name": "nginx-sandbox", - "namespace": "default", - "attempt": 1, - "uid": "hdishd83djaidwnduwk28bcsb" - }, - "annotations": { - "io.kubernetes.cri.untrusted-workload": "true" - }, - "linux": { - }, - "log_directory": "/tmp" -} -EOF -``` - -Create the pod in gVisor: - -```shell -SANDBOX_ID=$(sudo crictl runp sandbox.json) -``` - -### Run the nginx Container in the Sandbox - -Create the nginx container creation request: - -```shell -cat <<EOF | tee container.json -{ - "metadata": { - "name": "nginx" - }, - "image":{ - "image": "nginx" - }, - "log_path":"nginx.0.log", - "linux": { - } -} -EOF -``` - -Create the nginx container: - -```shell -CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json) -``` - -Start the nginx container: - -```shell -sudo crictl start ${CONTAINER_ID} -``` - -### Validate the container - -Inspect the created pod: - -```shell -sudo crictl inspectp ${SANDBOX_ID} -``` - -Inspect the nginx container: - -```shell -sudo crictl inspect ${CONTAINER_ID} -``` - -Verify that nginx is running in gVisor: - -```shell -sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor -``` diff --git a/g3doc/user_guide/containerd/quick_start.md b/g3doc/user_guide/containerd/quick_start.md deleted file mode 100644 index 02e82eb32..000000000 --- a/g3doc/user_guide/containerd/quick_start.md +++ /dev/null @@ -1,180 +0,0 @@ -# Containerd Quick Start - -This document describes how to use `containerd-shim-runsc-v1` with the -containerd runtime handler support on `containerd`. - -> ⚠️ NOTE: If you are using Kubernetes and set up your cluster using kubeadm you -> may run into issues. See the [FAQ](../FAQ.md#runtime-handler) for details. - -## Requirements - -- **runsc** and **containerd-shim-runsc-v1**: See the - [installation guide](/docs/user_guide/install/). -- **containerd**: See the [containerd website](https://containerd.io/) for - information on how to install containerd. **Minimal version supported: 1.3.9 - or 1.4.3.** - -## Configure containerd - -Update `/etc/containerd/config.toml`. Make sure `containerd-shim-runsc-v1` is in -`${PATH}` or in the same directory as `containerd` binary. - -```shell -cat <<EOF | sudo tee /etc/containerd/config.toml -disabled_plugins = ["restart"] -[plugins.linux] - shim_debug = true -[plugins.cri.containerd.runtimes.runsc] - runtime_type = "io.containerd.runsc.v1" -EOF -``` - -Restart `containerd`: - -```shell -sudo systemctl restart containerd -``` - -## Usage - -You can run containers in gVisor via containerd's CRI. - -### Install crictl - -Download and install the `crictl` binary: - -```shell -{ -wget https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.13.0/crictl-v1.13.0-linux-amd64.tar.gz -tar xf crictl-v1.13.0-linux-amd64.tar.gz -sudo mv crictl /usr/local/bin -} -``` - -Write the `crictl` configuration file: - -```shell -cat <<EOF | sudo tee /etc/crictl.yaml -runtime-endpoint: unix:///run/containerd/containerd.sock -EOF -``` - -### Create the nginx sandbox in gVisor - -Pull the nginx image: - -```shell -sudo crictl pull nginx -``` - -Create the sandbox creation request: - -```shell -cat <<EOF | tee sandbox.json -{ - "metadata": { - "name": "nginx-sandbox", - "namespace": "default", - "attempt": 1, - "uid": "hdishd83djaidwnduwk28bcsb" - }, - "linux": { - }, - "log_directory": "/tmp" -} -EOF -``` - -Create the pod in gVisor: - -```shell -SANDBOX_ID=$(sudo crictl runp --runtime runsc sandbox.json) -``` - -### Run the nginx container in the sandbox - -Create the nginx container creation request: - -```shell -cat <<EOF | tee container.json -{ - "metadata": { - "name": "nginx" - }, - "image":{ - "image": "nginx" - }, - "log_path":"nginx.0.log", - "linux": { - } -} -EOF -``` - -Create the nginx container: - -```shell -CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json) -``` - -Start the nginx container: - -```shell -sudo crictl start ${CONTAINER_ID} -``` - -### Validate the container - -Inspect the created pod: - -```shell -sudo crictl inspectp ${SANDBOX_ID} -``` - -Inspect the nginx container: - -```shell -sudo crictl inspect ${CONTAINER_ID} -``` - -Verify that nginx is running in gVisor: - -```shell -sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor -``` - -### Set up the Kubernetes RuntimeClass - -Install the RuntimeClass for gVisor: - -```shell -cat <<EOF | kubectl apply -f - -apiVersion: node.k8s.io/v1beta1 -kind: RuntimeClass -metadata: - name: gvisor -handler: runsc -EOF -``` - -Create a Pod with the gVisor RuntimeClass: - -```shell -cat <<EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - name: nginx-gvisor -spec: - runtimeClassName: gvisor - containers: - - name: nginx - image: nginx -EOF -``` - -Verify that the Pod is running: - -```shell -kubectl get pod nginx-gvisor -o wide -``` |