diff --git a/_data/toc.yaml b/_data/toc.yaml index 5ee50d780b4..a2a1ec6790a 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 00000000000..6807c5a74f0 --- /dev/null +++ b/engine/alternative-runtimes.md @@ -0,0 +1,235 @@ +--- +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. + +## What runtimes can I use? + +You can use any runtime that implements the containerd +[shim API](https://github.com/containerd/containerd/blob/main/runtime/v2/README.md){: target="blank" rel="noopener"}. +Such runtimes ship with a containerd shim, and you can use them without any +additional configuration. See [Use containerd shims](#use-containerd-shims). + +Examples of runtimes that implement their own containerd shims include: + +- [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"} + +You can also use runtimes designed as drop-in replacements for runc. Such +runtimes depend on the runc containerd shim for invoking the runtime binary. +You must manually register such runtimes in the daemon configuration. + +[youki](https://github.com/containers/youki){: target="blank" rel="noopener"} +is one example of a runtime that can function as a runc drop-in replacement. +Refer to the [youki example](#youki) explaining the setup. + +## Use containerd shims + +containerd shims let you use alternative runtimes without having to change the +configuration of the Docker daemon. To use a containerd shim, install the shim +binary on `PATH` on the system where the Docker daemon is running. + +To use a shim with `docker run`, specify the fully qualified name of the +runtime as the value to the `--runtime` flag: + +```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": { + "gvisor": { + "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 gvisor hello-world + ``` + +For more information about the configuration options for containerd shims, see +[Configure containerd shims](./reference/commandline/dockerd.md#configure-containerd-shims). + +## Examples + +The following examples show you how to set up and use alternative container +runtimes with Docker Engine. + +- [youki](#youki) +- [Wasmtime](#youki) + +### youki + +youki is a container runtime written in Rust. +youki claims to be faster and use less memory than runc, +making it a good choice for resource-constrained environments. + +youki functions as a drop-in replacement for runc, meaning it relies on the +runc shim to invoke the runtime binary. When you register runtimes acting as +runc replacements, you configure the path to the runtime executable, and +optionally a set of runtime arguments. For more information, see +[Configure runc drop-in replacements](./reference/commandline/dockerd.md#configure-runc-drop-in-replacements). + +To add youki as a container runtime: + +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 . - <