diff --git a/g3doc/user_guide/BUILD b/g3doc/user_guide/BUILD index 355dd49b3..b69aee12c 100644 --- a/g3doc/user_guide/BUILD +++ b/g3doc/user_guide/BUILD @@ -68,12 +68,3 @@ doc( permalink = "/docs/user_guide/platforms/", weight = "30", ) - -doc( - name = "runtimeclass", - src = "runtimeclass.md", - category = "User Guide", - permalink = "/docs/user_guide/runtimeclass/", - subcategory = "Advanced", - weight = "91", -) diff --git a/g3doc/user_guide/containerd/BUILD b/g3doc/user_guide/containerd/BUILD new file mode 100644 index 000000000..979d46105 --- /dev/null +++ b/g3doc/user_guide/containerd/BUILD @@ -0,0 +1,33 @@ +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", + permalink = "/docs/user_guide/containerd/containerd_11/", + subcategory = "Containerd", + weight = "99", +) diff --git a/g3doc/user_guide/containerd/configuration.md b/g3doc/user_guide/containerd/configuration.md new file mode 100644 index 000000000..5d485c24b --- /dev/null +++ b/g3doc/user_guide/containerd/configuration.md @@ -0,0 +1,70 @@ +# Containerd Advanced Configuration + +This document describes how to configure runtime options for +`containerd-shim-runsc-v1`. This follows the +[Containerd Quick Start](./quick_start.md) and requires containerd 1.2 or later. + +### 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 `ConfigPath` in the containerd runtime configuration. + +```shell +cat < Note: For containerd 1.2, the config file should named `config.toml` and +> located in the runtime root. By default, this is `/run/containerd/runsc`. + +The set of options that can be configured can be found in +[options.go](https://github.com/google/gvisor/blob/master/pkg/shim/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 +[Platforms Guide](../../architecture_guide/platforms.md). + +```shell +cat <= 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 < - -[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 <