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

4 files changed, 6 insertions, 399 deletions

diff --git a/shim/README.md b/shim/README.md
index c6824ebdc..75daf00ac 100644
--- a/shim/README.md
+++ b/shim/README.md
@@ -1,11 +1,10 @@
-# gVisor Containerd shims
+# Shim Overview
 
-There are various shims supported for differt versions of
-[containerd][containerd].
+Integration with containerd is done via a [shim][shims]. There are various shims
+supported for different versions of [containerd][containerd].
 
--   [Configure gvisor-containerd-shim (shim v1) (containerd ≤ 1.2)](v1/configure-gvisor-containerd-shim.md)
--   [Runtime Handler/RuntimeClass Quick Start (containerd >= 1.2)](v2/runtime-handler-quickstart.md)
--   [Runtime Handler/RuntimeClass Quick Start (shim v2) (containerd >= 1.2)](v2/runtime-handler-shim-v2-quickstart.md)
--   [Configure containerd-shim-runsc-v1 (shim v2) (containerd >= 1.3)](v2/configure-containerd-shim-runsc-v1.md)
+-   [Containerd 1.2+ (shim v2)](https://gvisor.dev/docs/user_guide/containerd/quick_start/)
+-   [Containerd 1.1 (shim v1)](https://gvisor.dev/docs/user_guide/containerd/containerd_11/)
 
 [containerd]: https://github.com/containerd/containerd
+[shims]: https://iximiuz.com/en/posts/implementing-container-runtime-shim/
diff --git a/shim/v1/README.md b/shim/v1/README.md
deleted file mode 100644
index 7aa4513a1..000000000
--- a/shim/v1/README.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# gvisor-containerd-shim
-
-> Note: This shim version is supported only for containerd versions less than
-> 1.2. If you are using a containerd version greater than or equal to 1.2, then
-> please use `containerd-shim-runsc-v1` (Shim API v1).
->
-> This containerd shim is supported only in a best-effort capacity.
-
-This document describes how to configure and use `gvisor-containerd-shim`.
-
-## Containerd Configuration
-
-To use this shim, you must configure `/etc/containerd/config.toml` as follows:
-
-```
-[plugins.linux]
-  shim = "/usr/bin/gvisor-containerd-shim"
-[plugins.cri.containerd.runtimes.gvisor]
-  runtime_type = "io.containerd.runtime.v1.linux"
-  runtime_engine = "/usr/bin/runsc"
-  runtime_root = "/run/containerd/runsc"
-```
-
-In order to pick-up the new configuration, you may need to restart containerd:
-
-```shell
-sudo systemctl restart containerd
-```
-
-## Shim Confguration
-
-The shim configuration is stored in `/etc/containerd/runsc.toml`. The
-configuration file supports two values.
-
-*   `runc_shim`: The path to the runc shim. This is used by
-    `gvisor-containerd-shim` to run standard containers.
-
-*   `runsc_config`: This is a set of key/value pairs that are converted into
-    `runsc` command line flags. You can learn more about which flags are
-    available by running `runsc flags`.
-
-For example, a configuration might look as follows:
-
-```
-runc_shim = "/usr/local/bin/containerd-shim"
-[runsc_config]
-platform = "kvm"
-debug = true
-debug-log = /var/log/%ID%/gvisor/
-```
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
-}
-```