From 9873b8ea3ee87b2659c0b45cd8a23f01a52d3735 Mon Sep 17 00:00:00 2001
From: Ian Lewis <ianlewis@google.com>
Date: Tue, 4 Aug 2020 02:41:34 -0700
Subject: Add shim documentation to the website.

Add three new doc pages to the website.

- A containerd quick start covering containerd 1.2. This is limited to shim v2
  and runtime class as the docs would get too complicated explaining all the
  combinations that are possible. We want folks to use shim v2 and runtime
  class anyway.
- An advanced configuration page. This covers containerd and
  containerd-shim-runsc-v1's configuration options.
- A page for old versions (i.e. containerd 1.1). Notes that this is deprecated
  and supported on a best-effort basis.

Fixes #3279

PiperOrigin-RevId: 324775563
---
 shim/v2/README.md                             |  91 ----------
 shim/v2/runtime-handler-shim-v2-quickstart.md | 251 --------------------------
 2 files changed, 342 deletions(-)
 delete mode 100644 shim/v2/README.md
 delete mode 100644 shim/v2/runtime-handler-shim-v2-quickstart.md

(limited to 'shim/v2')

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
-}
-```
-- 
cgit v1.2.3