diff options
Diffstat (limited to 'shim/v2')
| -rw-r--r-- | shim/v2/BUILD | 29 | ||||
| -rw-r--r-- | shim/v2/README.md | 91 | ||||
| -rw-r--r-- | shim/v2/runtime-handler-shim-v2-quickstart.md | 251 |
3 files changed, 0 insertions, 371 deletions
diff --git a/shim/v2/BUILD b/shim/v2/BUILD deleted file mode 100644 index ae4705935..000000000 --- a/shim/v2/BUILD +++ /dev/null @@ -1,29 +0,0 @@ -load("//tools:defs.bzl", "go_binary") -load("//website:defs.bzl", "doc") - -package(licenses = ["notice"]) - -go_binary( - name = "containerd-shim-runsc-v1", - srcs = [ - "main.go", - ], - static = True, - visibility = [ - "//visibility:public", - ], - deps = [ - "//pkg/shim/v2", - "@com_github_containerd_containerd//runtime/v2/shim:go_default_library", - ], -) - -doc( - name = "doc", - src = "README.md", - category = "User Guide", - permalink = "/docs/user_guide/containerd-shim-runsc-v1/", - subcategory = "Advanced", - visibility = ["//website:__pkg__"], - weight = "92", -) diff --git a/shim/v2/README.md b/shim/v2/README.md deleted file mode 100644 index 2aa7c21e3..000000000 --- a/shim/v2/README.md +++ /dev/null @@ -1,91 +0,0 @@ -# containerd-shim-runsc-v1 - -> Note: This shim version is the recommended shim for containerd versions -> greater than or equal to 1.2. For older versions of containerd, use -> `gvisor-containerd-shim`. - -This document describes how to configure and use `containerd-shim-runsc-v1`. - -## Configuring Containerd 1.2 - -To configure containerd 1.2 to use this shim, add the runtime to -`/etc/containerd/config.toml` as follows: - -``` -[plugins.cri.containerd.runtimes.runsc] - runtime_type = "io.containerd.runsc.v1" - runtime_root = "/run/containerd/runsc" -[plugins.cri.containerd.runtimes.runsc.options] - TypeUrl = "io.containerd.runsc.v1.options" -``` - -The configuration will optionally loaded from a file named `config.toml` in the -`runtime_root` configured above. - -In order to pick up the new configuration, you may need to restart containerd: - -```shell -sudo systemctl restart containerd -``` - -## Configuring Containerd 1.3 and above - -To configure containerd 1.3 to use this shim, add the runtime to -`/etc/containerd/config.toml` as follows: - -``` -[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" -``` - -The `ConfigPath` above will be used to provide a pointer to the configuration -file to be loaded. - -> Note that there will be configuration file loaded if `ConfigPath` is not set. - -In order to pick up the new configuration, you may need to restart containerd: - -```shell -sudo systemctl restart containerd -``` - -## Shim Confguration - -The shim configuration may carry the following options: - -* `shim_cgroup`: The cgroup to use for the shim itself. -* `io_uid`: The UID to use for pipes. -* `ui_gid`: The GID to use for pipes. -* `binary_name`: The runtime binary name (defaults to `runsc`). -* `root`: The root directory for the runtime. -* `runsc_config`: A dictionary of key-value pairs that will be passed to the - runtime as arguments. - -### Example: Enable the KVM platform - -gVisor enables the use of a number of platforms. This example shows how to -configure `containerd-shim-runsc-v1` to use gVisor with the KVM platform: - -```shell -cat <<EOF | sudo tee /etc/containerd/runsc.toml -[runsc_config] -platform = "kvm" -EOF -``` - -### Example: Enable 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 in the path of the -`debug-log` flag. - -```shell -cat <<EOF | sudo tee /etc/containerd/runsc.toml -[runsc_config] -debug = true -debug-log = /var/log/%ID%/gvisor.log -EOF -``` diff --git a/shim/v2/runtime-handler-shim-v2-quickstart.md b/shim/v2/runtime-handler-shim-v2-quickstart.md deleted file mode 100644 index 3b88ca74b..000000000 --- a/shim/v2/runtime-handler-shim-v2-quickstart.md +++ /dev/null @@ -1,251 +0,0 @@ -# Runtime Handler Quickstart (Shim V2) - -This document describes how to install and run `containerd-shim-runsc-v1` using -the containerd runtime handler support. This requires containerd 1.2 or later. - -## Requirements - -- **runsc**: See the [gVisor documentation](https://github.com/google/gvisor) - for information on how to install runsc. -- **containerd**: See the [containerd website](https://containerd.io/) for - information on how to install containerd. - -## Install - -### Install containerd-shim-runsc-v1 - -1. Build and install `containerd-shim-runsc-v1`. - -<!-- TODO: Use a release once we have one available. --> - -[embedmd]:# (../test/e2e/shim-install.sh shell /{ # Step 1\(dev\)/ /^}/) - -```shell -{ # Step 1(dev): Build and install gvisor-containerd-shim and containerd-shim-runsc-v1 - make - sudo make install -} -``` - -### Configure containerd - -1. Update `/etc/containerd/config.toml`. Make sure `containerd-shim-runsc-v1` - is in `${PATH}`. - -[embedmd]:# (../test/e2e/runtime-handler-shim-v2/install.sh shell /{ # Step 1/ /^}/) - -```shell -{ # Step 1: Create containerd config.toml -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 -} -``` - -1. Restart `containerd` - -```shell -sudo systemctl restart containerd -``` - -## Usage - -You can run containers in gVisor via containerd's CRI. - -### Install crictl - -1. Download and install the crictl binary: - -[embedmd]:# (../test/e2e/crictl-install.sh shell /{ # Step 1/ /^}/) - -```shell -{ # Step 1: Download crictl -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 -} -``` - -1. Write the crictl configuration file - -[embedmd]:# (../test/e2e/crictl-install.sh shell /{ # Step 2/ /^}/) - -```shell -{ # Step 2: Configure crictl -cat <<EOF | sudo tee /etc/crictl.yaml -runtime-endpoint: unix:///run/containerd/containerd.sock -EOF -} -``` - -### Create the nginx Sandbox in gVisor - -1. Pull the nginx image - -[embedmd]:# (../test/e2e/runtime-handler/usage.sh shell /{ # Step 1/ /^}/) - -```shell -{ # Step 1: Pull the nginx image -sudo crictl pull nginx -} -``` - -1. Create the sandbox creation request - -[embedmd]:# (../test/e2e/runtime-handler/usage.sh shell /{ # Step 2/ /^EOF\n}/) - -```shell -{ # Step 2: Create sandbox.json -cat <<EOF | tee sandbox.json -{ - "metadata": { - "name": "nginx-sandbox", - "namespace": "default", - "attempt": 1, - "uid": "hdishd83djaidwnduwk28bcsb" - }, - "linux": { - }, - "log_directory": "/tmp" -} -EOF -} -``` - -1. Create the pod in gVisor - -[embedmd]:# (../test/e2e/runtime-handler/usage.sh shell /{ # Step 3/ /^}/) - -```shell -{ # Step 3: Create the sandbox -SANDBOX_ID=$(sudo crictl runp --runtime runsc sandbox.json) -} -``` - -### Run the nginx Container in the Sandbox - -1. Create the nginx container creation request - -[embedmd]:# (../test/e2e/run-container.sh shell /{ # Step 1/ /^EOF\n}/) - -```shell -{ # Step 1: Create nginx container config -cat <<EOF | tee container.json -{ - "metadata": { - "name": "nginx" - }, - "image":{ - "image": "nginx" - }, - "log_path":"nginx.0.log", - "linux": { - } -} -EOF -} -``` - -1. Create the nginx container - -[embedmd]:# (../test/e2e/run-container.sh shell /{ # Step 2/ /^}/) - -```shell -{ # Step 2: Create nginx container -CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json) -} -``` - -1. Start the nginx container - -[embedmd]:# (../test/e2e/run-container.sh shell /{ # Step 3/ /^}/) - -```shell -{ # Step 3: Start nginx container -sudo crictl start ${CONTAINER_ID} -} -``` - -### Validate the container - -1. Inspect the created pod - -[embedmd]:# (../test/e2e/validate.sh shell /{ # Step 1/ /^}/) - -```shell -{ # Step 1: Inspect the pod -sudo crictl inspectp ${SANDBOX_ID} -} -``` - -1. Inspect the nginx container - -[embedmd]:# (../test/e2e/validate.sh shell /{ # Step 2/ /^}/) - -```shell -{ # Step 2: Inspect the container -sudo crictl inspect ${CONTAINER_ID} -} -``` - -1. Verify that nginx is running in gVisor - -[embedmd]:# (../test/e2e/validate.sh shell /{ # Step 3/ /^}/) - -```shell -{ # Step 3: Check dmesg -sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor -} -``` - -### Set up the Kubernetes Runtime Class - -1. Install the Runtime Class for gVisor - -[embedmd]:# (../test/e2e/runtimeclass-install.sh shell /{ # Step 1/ /^}/) - -```shell -{ # Step 1: Install a RuntimeClass -cat <<EOF | kubectl apply -f - -apiVersion: node.k8s.io/v1beta1 -kind: RuntimeClass -metadata: - name: gvisor -handler: runsc -EOF -} -``` - -1. Create a Pod with the gVisor Runtime Class - -[embedmd]:# (../test/e2e/runtimeclass-install.sh shell /{ # Step 2/ /^}/) - -```shell -{ # Step 2: Create a pod -cat <<EOF | kubectl apply -f - -apiVersion: v1 -kind: Pod -metadata: - name: nginx-gvisor -spec: - runtimeClassName: gvisor - containers: - - name: nginx - image: nginx -EOF -} -``` - -1. Verify that the Pod is running - -[embedmd]:# (../test/e2e/runtimeclass-install.sh shell /{ # Step 3/ /^}/) - -```shell -{ # Step 3: Get the pod -kubectl get pod nginx-gvisor -o wide -} -``` |