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
This commit is contained in:
Ian Lewis
gVisor bot
parent
a02b7534f2
commit
9873b8ea3e
|
|
@ -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",
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
)
|
||||
|
|
@ -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 <<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"
|
||||
[plugins.cri.containerd.runtimes.runsc.options]
|
||||
TypeUrl = "io.containerd.runsc.v1.options"
|
||||
# containerd 1.3 only!
|
||||
ConfigPath = "/etc/containerd/runsc.toml"
|
||||
EOF
|
||||
```
|
||||
|
||||
When you are done restart containerd to pick up the new configuration files.
|
||||
|
||||
```shell
|
||||
sudo systemctl restart containerd
|
||||
```
|
||||
|
||||
### Configure `/etc/containerd/runsc.toml`
|
||||
|
||||
> 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 <<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, and "%COMMAND%" with the
|
||||
runsc command (run, boot, etc.) in the path of the `debug-log` flag.
|
||||
|
||||
Find out more about debugging in the [debugging guide](../debugging.md).
|
||||
|
||||
```shell
|
||||
cat <<EOF | sudo tee /etc/containerd/runsc.toml
|
||||
[runsc_config]
|
||||
debug=true
|
||||
debug-log=/var/log/%ID%/gvisor.%COMMAND%.log
|
||||
EOF
|
||||
```
|
||||
|
|
@ -0,0 +1,163 @@
|
|||
# Older Versions (containerd 1.1)
|
||||
|
||||
This document describes how to install and run the `gvisor-containerd-shim`
|
||||
using the untrusted workload CRI extension. This requires `containerd` 1.1 or
|
||||
later.
|
||||
|
||||
*Note: The untrusted workload CRI extension is deprecated by containerd and
|
||||
`gvisor-containerd-shim` is maintained on a best-effort basis. If you are using
|
||||
containerd 1.2+, please see the
|
||||
[containerd 1.2+ documentation](./quick_start.md) and use
|
||||
`containerd-shim-runsc-v1`.*
|
||||
|
||||
## Requirements
|
||||
|
||||
- **runsc** and **gvisor-containerd-shim**: See the
|
||||
[installation guide](/docs/user_guide/install/).
|
||||
- **containerd**: See the [containerd website](https://containerd.io/) for
|
||||
information on how to install containerd.
|
||||
|
||||
## Configure containerd
|
||||
|
||||
Create the configuration for the gvisor shim in
|
||||
`/etc/containerd/gvisor-containerd-shim.toml`:
|
||||
|
||||
```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"
|
||||
EOF
|
||||
```
|
||||
|
||||
Update `/etc/containerd/config.toml`. Be sure to update the path to
|
||||
`gvisor-containerd-shim` and `runsc` if necessary:
|
||||
|
||||
```shell
|
||||
cat <<EOF | sudo tee /etc/containerd/config.toml
|
||||
disabled_plugins = ["restart"]
|
||||
[plugins.linux]
|
||||
shim = "/usr/local/bin/gvisor-containerd-shim"
|
||||
shim_debug = true
|
||||
[plugins.cri.containerd.untrusted_workload_runtime]
|
||||
runtime_type = "io.containerd.runtime.v1.linux"
|
||||
runtime_engine = "/usr/local/bin/runsc"
|
||||
runtime_root = "/run/containerd/runsc"
|
||||
EOF
|
||||
```
|
||||
|
||||
Restart `containerd`:
|
||||
|
||||
```shell
|
||||
sudo systemctl restart containerd
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
You can run containers in gVisor via containerd's CRI.
|
||||
|
||||
### Install crictl
|
||||
|
||||
Download and install the `crictl` binary:
|
||||
|
||||
```shell
|
||||
{
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
Write the `crictl` configuration file:
|
||||
|
||||
```shell
|
||||
cat <<EOF | sudo tee /etc/crictl.yaml
|
||||
runtime-endpoint: unix:///run/containerd/containerd.sock
|
||||
EOF
|
||||
```
|
||||
|
||||
### Create the nginx Sandbox in gVisor
|
||||
|
||||
Pull the nginx image:
|
||||
|
||||
```shell
|
||||
sudo crictl pull nginx
|
||||
```
|
||||
|
||||
Create the sandbox creation request:
|
||||
|
||||
```shell
|
||||
cat <<EOF | tee sandbox.json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "nginx-sandbox",
|
||||
"namespace": "default",
|
||||
"attempt": 1,
|
||||
"uid": "hdishd83djaidwnduwk28bcsb"
|
||||
},
|
||||
"annotations": {
|
||||
"io.kubernetes.cri.untrusted-workload": "true"
|
||||
},
|
||||
"linux": {
|
||||
},
|
||||
"log_directory": "/tmp"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Create the pod in gVisor:
|
||||
|
||||
```shell
|
||||
SANDBOX_ID=$(sudo crictl runp sandbox.json)
|
||||
```
|
||||
|
||||
### Run the nginx Container in the Sandbox
|
||||
|
||||
Create the nginx container creation request:
|
||||
|
||||
```shell
|
||||
cat <<EOF | tee container.json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"image":{
|
||||
"image": "nginx"
|
||||
},
|
||||
"log_path":"nginx.0.log",
|
||||
"linux": {
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Create the nginx container:
|
||||
|
||||
```shell
|
||||
CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json)
|
||||
```
|
||||
|
||||
Start the nginx container:
|
||||
|
||||
```shell
|
||||
sudo crictl start ${CONTAINER_ID}
|
||||
```
|
||||
|
||||
### Validate the container
|
||||
|
||||
Inspect the created pod:
|
||||
|
||||
```shell
|
||||
sudo crictl inspectp ${SANDBOX_ID}
|
||||
```
|
||||
|
||||
Inspect the nginx container:
|
||||
|
||||
```shell
|
||||
sudo crictl inspect ${CONTAINER_ID}
|
||||
```
|
||||
|
||||
Verify that nginx is running in gVisor:
|
||||
|
||||
```shell
|
||||
sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor
|
||||
```
|
||||
|
|
@ -0,0 +1,176 @@
|
|||
# Containerd Quick Start
|
||||
|
||||
This document describes how to install and configure `containerd-shim-runsc-v1`
|
||||
using the containerd runtime handler support on `containerd` 1.2 or later.
|
||||
|
||||
## Requirements
|
||||
|
||||
- **runsc** and **containerd-shim-runsc-v1**: See the
|
||||
[installation guide](/docs/user_guide/install/).
|
||||
- **containerd**: See the [containerd website](https://containerd.io/) for
|
||||
information on how to install containerd.
|
||||
|
||||
## Configure containerd
|
||||
|
||||
Update `/etc/containerd/config.toml`. Make sure `containerd-shim-runsc-v1` is in
|
||||
`${PATH}` or in the same directory as `containerd` binary.
|
||||
|
||||
```shell
|
||||
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
|
||||
```
|
||||
|
||||
Restart `containerd`:
|
||||
|
||||
```shell
|
||||
sudo systemctl restart containerd
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
You can run containers in gVisor via containerd's CRI.
|
||||
|
||||
### Install crictl
|
||||
|
||||
Download and install the `crictl`` binary:
|
||||
|
||||
```shell
|
||||
{
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
Write the `crictl` configuration file:
|
||||
|
||||
```shell
|
||||
cat <<EOF | sudo tee /etc/crictl.yaml
|
||||
runtime-endpoint: unix:///run/containerd/containerd.sock
|
||||
EOF
|
||||
```
|
||||
|
||||
### Create the nginx sandbox in gVisor
|
||||
|
||||
Pull the nginx image:
|
||||
|
||||
```shell
|
||||
sudo crictl pull nginx
|
||||
```
|
||||
|
||||
Create the sandbox creation request:
|
||||
|
||||
```shell
|
||||
cat <<EOF | tee sandbox.json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "nginx-sandbox",
|
||||
"namespace": "default",
|
||||
"attempt": 1,
|
||||
"uid": "hdishd83djaidwnduwk28bcsb"
|
||||
},
|
||||
"linux": {
|
||||
},
|
||||
"log_directory": "/tmp"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Create the pod in gVisor:
|
||||
|
||||
```shell
|
||||
SANDBOX_ID=$(sudo crictl runp --runtime runsc sandbox.json)
|
||||
```
|
||||
|
||||
### Run the nginx container in the sandbox
|
||||
|
||||
Create the nginx container creation request:
|
||||
|
||||
```shell
|
||||
cat <<EOF | tee container.json
|
||||
{
|
||||
"metadata": {
|
||||
"name": "nginx"
|
||||
},
|
||||
"image":{
|
||||
"image": "nginx"
|
||||
},
|
||||
"log_path":"nginx.0.log",
|
||||
"linux": {
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Create the nginx container:
|
||||
|
||||
```shell
|
||||
CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json)
|
||||
```
|
||||
|
||||
Start the nginx container:
|
||||
|
||||
```shell
|
||||
sudo crictl start ${CONTAINER_ID}
|
||||
```
|
||||
|
||||
### Validate the container
|
||||
|
||||
Inspect the created pod:
|
||||
|
||||
```shell
|
||||
sudo crictl inspectp ${SANDBOX_ID}
|
||||
```
|
||||
|
||||
Inspect the nginx container:
|
||||
|
||||
```shell
|
||||
sudo crictl inspect ${CONTAINER_ID}
|
||||
```
|
||||
|
||||
Verify that nginx is running in gVisor:
|
||||
|
||||
```shell
|
||||
sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor
|
||||
```
|
||||
|
||||
### Set up the Kubernetes RuntimeClass
|
||||
|
||||
Install the RuntimeClass for gVisor:
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: node.k8s.io/v1beta1
|
||||
kind: RuntimeClass
|
||||
metadata:
|
||||
name: gvisor
|
||||
handler: runsc
|
||||
EOF
|
||||
```
|
||||
|
||||
Create a Pod with the gVisor RuntimeClass:
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: nginx-gvisor
|
||||
spec:
|
||||
runtimeClassName: gvisor
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx
|
||||
EOF
|
||||
```
|
||||
|
||||
Verify that the Pod is running:
|
||||
|
||||
```shell
|
||||
kubectl get pod nginx-gvisor -o wide
|
||||
```
|
||||
|
|
@ -6,17 +6,15 @@ with Kubernetes.
|
|||
## Using Minikube
|
||||
|
||||
gVisor can run sandboxed containers in a Kubernetes cluster with Minikube. After
|
||||
the gVisor addon is enabled, pods with `io.kubernetes.cri.untrusted-workload`
|
||||
the gVisor addon is enabled, pods with a `gvisor` [Runtime Class][runtimeclass]
|
||||
set to true will execute with `runsc`. Follow [these instructions][minikube] to
|
||||
enable gVisor addon.
|
||||
|
||||
## Using Containerd
|
||||
|
||||
You can also setup Kubernetes nodes to run pods in gvisor using the
|
||||
[containerd][containerd] CRI runtime and the `gvisor-containerd-shim`. You can
|
||||
use either the `io.kubernetes.cri.untrusted-workload` annotation or
|
||||
[RuntimeClass][runtimeclass] to run Pods with `runsc`. You can find instructions
|
||||
[here][gvisor-containerd-shim].
|
||||
You can also setup Kubernetes nodes to run pods in gVisor using
|
||||
[containerd][containerd] and the gVisor containerd shim. You can find
|
||||
instructions in the [Containerd Quick Start][gvisor-containerd].
|
||||
|
||||
## Using GKE Sandbox
|
||||
|
||||
|
|
@ -31,6 +29,6 @@ WordPress site. You can view the full documentation [here][gke-sandbox-docs].
|
|||
[gke]: https://cloud.google.com/kubernetes-engine/
|
||||
[gke-sandbox]: https://cloud.google.com/kubernetes-engine/sandbox/
|
||||
[gke-sandbox-docs]: https://cloud.google.com/kubernetes-engine/docs/how-to/sandbox-pods
|
||||
[gvisor-containerd-shim]: https://github.com/google/gvisor-containerd-shim
|
||||
[gvisor-containerd]: /docs/user_guide/containerd/quick_start/
|
||||
[runtimeclass]: https://kubernetes.io/docs/concepts/containers/runtime-class/
|
||||
[wordpress-quick]: /docs/tutorials/kubernetes/
|
||||
|
|
|
|||
|
|
@ -1,46 +0,0 @@
|
|||
# RuntimeClass
|
||||
|
||||
First, follow the appropriate installation instructions for your version of
|
||||
containerd.
|
||||
|
||||
* For 1.1 or lower, use `gvisor-containerd-shim`.
|
||||
* For 1.2 or higher, use `containerd-shim-runsc-v1`.
|
||||
|
||||
# Set up the Kubernetes RuntimeClass
|
||||
|
||||
Creating the [RuntimeClass][runtimeclass] in Kubernetes is simple once the
|
||||
runtime is available for containerd:
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: node.k8s.io/v1beta1
|
||||
kind: RuntimeClass
|
||||
metadata:
|
||||
name: gvisor
|
||||
handler: runsc
|
||||
EOF
|
||||
```
|
||||
|
||||
Pods can now be created using this RuntimeClass:
|
||||
|
||||
```shell
|
||||
cat <<EOF | kubectl apply -f -
|
||||
apiVersion: v1
|
||||
kind: Pod
|
||||
metadata:
|
||||
name: nginx-gvisor
|
||||
spec:
|
||||
runtimeClassName: gvisor
|
||||
containers:
|
||||
- name: nginx
|
||||
image: nginx
|
||||
EOF
|
||||
```
|
||||
|
||||
You can verify that the Pod is running via this RuntimeClass:
|
||||
|
||||
```shell
|
||||
kubectl get pod nginx-gvisor -o wide
|
||||
```
|
||||
|
||||
[runtimeclass]: https://kubernetes.io/docs/concepts/containers/runtime-class/
|
||||
|
|
@ -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/
|
||||
|
|
|
|||
|
|
@ -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/
|
||||
```
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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
|
||||
}
|
||||
```
|
||||
|
|
@ -149,6 +149,9 @@ docs(
|
|||
"//g3doc/user_guide:install",
|
||||
"//g3doc/user_guide:networking",
|
||||
"//g3doc/user_guide:platforms",
|
||||
"//g3doc/user_guide/containerd:configuration",
|
||||
"//g3doc/user_guide/containerd:containerd_11",
|
||||
"//g3doc/user_guide/containerd:quick_start",
|
||||
"//g3doc/user_guide/quick_start:docker",
|
||||
"//g3doc/user_guide/quick_start:kubernetes",
|
||||
"//g3doc/user_guide/quick_start:oci",
|
||||
|
|
|
|||
Loading…
Reference in New Issue