diff --git a/_data/toc.yaml b/_data/toc.yaml index 5ee50d780b4b..a2a1ec6790a3 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1542,6 +1542,8 @@ manuals: section: - sectiontitle: Container runtime section: + - path: /engine/alternative-runtimes/ + title: Alternative container runtimes - path: /config/containers/resource_constraints/ title: Configure runtime resource constraints - path: /config/containers/runmetrics/ diff --git a/engine/alternative-runtimes.md b/engine/alternative-runtimes.md new file mode 100644 index 000000000000..119d0828c66b --- /dev/null +++ b/engine/alternative-runtimes.md @@ -0,0 +1,292 @@ +--- +title: Alternative container runtimes +description: | + Docker Engine uses runc as the default container runtime, but you + can specify alternative runtimes using the CLI or by configuring + the daemon +keywords: engine, runtime, containerd, runtime v2, shim +--- + +Docker Engine uses containerd for managing the container lifecycle, +which includes creating, starting, and stopping containers. +By default, containerd uses runc as its container runtime. + +containerd supports a +[shim API](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md){: target="blank" rel="noopener"} +which lets you select a different container runtime. + +Examples of alternative runtimes that you can use include: + +- [youki](https://github.com/containers/youki){: target="blank" rel="noopener"} +- [Wasmtime](https://wasmtime.dev/){: target="blank" rel="noopener"} +- [gVisor](https://github.com/google/gvisor){: target="blank" rel="noopener"} +- [Kata Containers](https://katacontainers.io/){: target="blank" rel="noopener"} + +## How to use alternative runtimes + +There are different ways you can go about selecting an alternative container +runtime. + +- [Register additional runtimes](#register-additional-runtimes) +- [Use containerd shims](#use-containerd-shims) +- [Configure the default runtime](#configure-the-default-runtime) + +### Register additional runtimes + +You can register additional runtimes with the Docker daemon on startup. +This doesn't change the default runtime, but makes it possible to select +alternative runtimes on a per-container basis. + +The following examples show how to register `youki` as a container runtime: + +- Using the daemon configuration file (`/etc/docker/daemon.json`) + + ```json + { + "runtimes": { + "youki": { + "path": "/usr/bin/youki", + "runtimeArgs": ["--debug"] + } + } + } + ``` + +- Using the `dockerd` CLI + + ```console + $ dockerd --add-runtime youki=/usr/bin/youki + ``` + +> **Note** +> +> You can specify additional arguments when you register a runtime using the +> configuration file, but not when you use the CLI flag. + +### Use containerd shims + +Docker Engine supports the use of containerd runtime shims. +Using shims, you can use alternative runtimes without having to configure or +restart the Docker daemon. + +To use a containerd shim without registering it in the daemon configuration, +you must install the shim binary on `PATH` on the system where the Docker +daemon is running. With the shim installed, you can select the shim with +`docker run` using the shim's fully qualified name. + +The fully qualified name is the same as what you would put as `runtime_type` +in the containerd configuration. For example: + +- `io.containerd.runc.v2` +- `io.containerd.runsc.v1` +- `io.containerd.kata.v2` + +The following `docker run` command uses the Kata Containers runtime, provided +that the shim binary is installed on `PATH`. + +```console +$ docker run --runtime io.containerd.kata.v2 hello-world +``` + +#### Use a containerd shim without installing on PATH + +You can use a shim without installing it on `PATH`, in which case you need to +register the shim in the daemon configuration as follows: + +```json +{ + "runtimes": { + "foo": { + "runtimeType": "/path/to/containerd-shim-foobar-v1" + } + } +} +``` + +To use the shim, specify the name that you assigned to it: + +```console +$ docker run --runtime foo hello-world +``` + +#### Configure shims + +If you need to pass additional configuration for a containerd shim, you can +use the `runtimes` option in the daemon configuration file. + +1. Edit the daemon configuration file by adding a `runtimes` entry for the + shim you want to configure. + + - Specify the fully qualified name for the runtime in `runtimeType` key + - Add your runtime configuration under the `options` key + + ```json + { + "runtimes": { + "runsc": { + "runtimeType": "io.containerd.runsc.v1", + "options": { + "TypeUrl": "io.containerd.runsc.v1.options", + "ConfigPath": "/etc/containerd/runsc.toml" + } + } + } + } + ``` + +2. Reload the daemon's configuration. + + ```console + # systemctl reload docker + ``` + +3. Use the customized runtime using the `--runtime` flag for `docker run`. + + ```console + $ docker run --runtime runsc ... + ``` + +### Configure the default runtime + +You can change the default runtime of the daemon, using the `default-runtime` +option. + +The following examples show how to configure the daemon to use gVisor (`runsc`) +as the default runtime: + +- Using the daemon configuration file (`/etc/docker/daemon.json`) + + ```json + { + "default-runtime": "io.containerd.runsc.v1" + } + ``` + +- Using the `dockerd` CLI + + ```console + $ dockerd --default-runtime io.containerd.runsc.v1 + ``` + +You can specify either a runtime type, or the name of a registered runtime. +The runtime executable must be installed on `PATH`. + +## Tutorials + +The following sections show examples on how to use alternative container +runtimes. The examples cover the following runtimes: + +- [youki](#youki) +- [Wasmtime](#youki) + +The example commands in these tutorials assume an Ubuntu or Debian system. + +### youki + +youki is a container runtime written in Rust. +It claims to be faster and use less memory than runc, +making it a good choice for resource-constrained environments. + +The following procedure shows how to install youki, configure Docker daemon, +and use youki as the container runtime with Docker. + +1. Install youki and its dependencies. + + For instructions, refer to the + [official setup guide](https://containers.github.io/youki/user/basic_setup.html){: target="\_blank" rel="noopener"}. + +2. Register youki as a runtime for Docker by editing the Docker daemon + configuration file, located at `/etc/docker/daemon.json` by default. + + The `path` key should specify the path to wherever you installed youki. + + ```console + # cat > /etc/docker/daemon.json < **Note** + > + > This is an experimental feature. + + ```json + { + "features": { + "containerd-snapshotter": true + } + } + ``` + +2. Restart the Docker daemon. + + ```console + # systemctl restart docker + ``` + +3. Install the Wasmtime containerd shim on `PATH`. + + The following command Dockerfile builds the Wasmtime binary from source + and exports it to `./containerd-shim-wasmtime-v1`. + + ```console + $ docker build --output . - <