From ec51ea57e2a7ec6eb15200a7efd1dd6245381ec1 Mon Sep 17 00:00:00 2001
From: Ian Lewis <ianlewis@google.com>
Date: Wed, 25 Mar 2020 08:28:36 +0900
Subject: [PATCH] Config docs (#54)

* Updated configuration docs to be more consistent

* Add links to configuration docs

* Add links to top README

* Fix markdown formatting
---
 README.md                                  | 15 ++++---
 docs/README.md                             |  9 ++--
 docs/configure-containerd-shim-runsc-v1.md | 50 +++++++++++++++++-----
 docs/configure-gvisor-containerd-shim.md   | 42 ++++++++++++++++++
 4 files changed, 97 insertions(+), 19 deletions(-)
 create mode 100644 docs/configure-gvisor-containerd-shim.md

diff --git a/README.md b/README.md
index 5480ab905..40a474c4f 100644
--- a/README.md
+++ b/README.md
@@ -7,14 +7,19 @@ gvisor-containerd-shim is a containerd shim for [gVisor](https://github.com/goog
 
 ## Requirements
 
-- gvisor (runsc) >= 2018-12-07
-- containerd, containerd-shim >= 1.1
+-   gvisor (runsc) >= 2018-12-07
+-   containerd, containerd-shim >= 1.1
 
 ## Installation
 
-- [Untrusted Workload Quick Start (containerd >=1.1)](docs/untrusted-workload-quickstart.md)
-- [Runtime Handler/RuntimeClass Quick Start (containerd >=1.2)](docs/runtime-handler-quickstart.md)
-- [Runtime Handler/RuntimeClass Quick Start (shim v2) (containerd >=1.2)](docs/runtime-handler-shim-v2-quickstart.md)
+-   [Untrusted Workload Quick Start (containerd >=1.1)](docs/untrusted-workload-quickstart.md)
+-   [Runtime Handler/RuntimeClass Quick Start (containerd >=1.2)](docs/runtime-handler-quickstart.md)
+-   [Runtime Handler/RuntimeClass Quick Start (shim v2) (containerd >=1.2)](docs/runtime-handler-shim-v2-quickstart.md)
+
+## Configuration
+
+-   [Configure containerd-shim-runsc-v1 (shim v2) (containerd >= 1.3)](docs/configure-containerd-shim-runsc-v1.md)
+-   [Configure gvisor-containerd-shim (shim v1) (containerd &lt;= 1.2)](docs/configure-gvisor-containerd-shim.md)
 
 # Contributing
 
diff --git a/docs/README.md b/docs/README.md
index 389c911ea..f1091f934 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,7 +2,8 @@
 
 Everything you need to know about gvisor-containerd-shim
 
-- [Untrusted Workload Quick Start (containerd >=1.1)](untrusted-workload-quickstart.md)
-- [Runtime Handler Quick Start (containerd >=1.2)](runtime-handler-quickstart.md)
-- [Runtime Handler Quick Start (shim v2) (containerd >=1.2)](runtime-handler-shim-v2-quickstart.md)
-- [Configure containerd-shim-runsc-v1 (shim v2) (containerd >= 1.3)](configure-containerd-shim-runsc-v1.md)
+-   [Untrusted Workload Quick Start (containerd >=1.1)](untrusted-workload-quickstart.md)
+-   [Runtime Handler Quick Start (containerd >=1.2)](runtime-handler-quickstart.md)
+-   [Runtime Handler Quick Start (shim v2) (containerd >=1.2)](runtime-handler-shim-v2-quickstart.md)
+-   [Configure containerd-shim-runsc-v1 (shim v2) (containerd >= 1.3)](configure-containerd-shim-runsc-v1.md)
+-   [Configure gvisor-containerd-shim (shim v1) (containerd &lt;= 1.2)](configure-gvisor-containerd-shim.md)
diff --git a/docs/configure-containerd-shim-runsc-v1.md b/docs/configure-containerd-shim-runsc-v1.md
index b3be30ce7..977ceacbd 100644
--- a/docs/configure-containerd-shim-runsc-v1.md
+++ b/docs/configure-containerd-shim-runsc-v1.md
@@ -1,13 +1,15 @@
 # Configure containerd-shim-runsc-v1 (Shim V2)
 
-This document describes how to configure runtime options for `containerd-shim-runsc-v1`.
-This is follows on to the instructions of [Runtime Handler Quick Start (shim v2) (containerd >=1.2)](runtime-handler-shim-v2-quickstart.md) and requires containerd 1.3 or later.
+This document describes how to configure runtime options for
+`containerd-shim-runsc-v1`.  This is follows on to the instructions of
+[Runtime Handler Quick Start (shim v2) (containerd >=1.2)](runtime-handler-shim-v2-quickstart.md)
+and requires containerd 1.3 or later.
 
-## Configuration
+### Update `/etc/containerd/config.toml` to point to a configuration file for `containerd-shim-runsc-v1`.
 
-`containerd-shim-runsc-v1` supports a few different configuration options based on the version of containerd that is used. For versions >= 1.3, it supports a configurable config path in the containerd runtime configuration.
-
-1. Update `/etc/containerd/config.toml` to point to a configuration file for `containerd-shim-runsc-v1`.
+`containerd-shim-runsc-v1` supports a few different configuration options based
+on the version of containerd that is used. For versions >= 1.3, it supports a
+configurable config path in the containerd runtime configuration.
 
 ```shell
 { # Step 1: Update runtime options for runsc in containerd config.toml
@@ -24,18 +26,46 @@ EOF
 }
 ```
 
-2. Configure `/etc/containerd/runsc.toml` with the desired options. The set of options that can be configured can be found in [options.go](../pkg/v2/options/options.go). This example shows how to configure `containerd-shim-runsc-v1` to use gvisor with the kvm platform.
+### Configure `/etc/containerd/runsc.toml`
+
+The set of options that can be configured can be found in
+[options.go](../pkg/v2/options/options.go).
+
+#### 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.
+
+Find out more about platform in the
+(gVisor documentation)[https://gvisor.dev/docs/user_guide/platforms/].
 
 ```shell
-{ # Step 2: Create containerd-shim-runsc-v1 runtime options config
 cat <<EOF | sudo tee /etc/containerd/runsc.toml
 [runsc_config]
 platform = "kvm"
 EOF
-}
 ```
 
-3. Restart `containerd`
+### 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.
+
+Find out more about debugging in the
+(gVisor documentation)[https://gvisor.dev/docs/user_guide/debugging/].
+
+```shell
+cat <<EOF | sudo tee /etc/containerd/runsc.toml
+[runsc_config]
+  debug=true
+  debug-log=/var/log/%ID%/gvisor.log
+EOF
+```
+
+## Restart `containerd`
+
+When you are done restart containerd to pick up the new configuration files.
 
 ```shell
 sudo systemctl restart containerd
diff --git a/docs/configure-gvisor-containerd-shim.md b/docs/configure-gvisor-containerd-shim.md
new file mode 100644
index 000000000..40151da56
--- /dev/null
+++ b/docs/configure-gvisor-containerd-shim.md
@@ -0,0 +1,42 @@
+# Configure gvisor-containerd-shim (Shim V1)
+
+This document describes how to configure runtime options for `gvisor-containerd-shim`.
+
+The shim configuration is stored in `/etc/containerd/gvisor-containerd-shim.toml`.  The configuration file supports two values.
+
+`runc_shim`: The path to the runc shim. This is used by the gvisor-containerd-shim to run normal 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`.
+
+## Example: Enable the KVM platform
+
+gVisor enables the use of a number of platforms. This configuration enables the
+KVM platform.
+
+Find out more about platform in the
+(gVisor documentation)[https://gvisor.dev/docs/user_guide/platforms/].
+
+```shell
+cat <<EOF | sudo tee /etc/containerd/gvisor-containerd-shim.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.
+
+Find out more about debugging in the
+(gVisor documentation)[https://gvisor.dev/docs/user_guide/debugging/].
+
+```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"
+[runsc_config]
+  debug=true
+  debug-log=/var/log/%ID%/gvisor.log
+EOF
+```