engine: instructions on using alternative container runtimes

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

_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/

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 <<EOF
+   {
+     "runtimes": {
+       "youki": {
+         "path": "/usr/local/bin/youki"
+       }
+     }
+   }
+   EOF
+   ```
+
+3. Restart the Docker daemon.
+
+   ```console
+   # systemctl restart docker
+   ```
+
+4. Run a container that uses youki as a runtime.
+
+   ```console
+   $ docker run --rm --runtime youki hello-world
+   ```
+
+### Wasmtime
+
+Wasmtime is a
+[Bytecode Alliance](https://bytecodealliance.org/){:target="\_blank" rel="noopener"}
+project, and a Wasm runtime that lets you run Wasm containers.
+Running Wasm containers with Docker provides two layers of security.
+You get all the benefits from container isolation,
+plus the added sandboxing provided by the Wasm runtime environment.
+
+The following procedure shows how to install the Wasmtime containerd shim,
+and how to run a Wasm container using the shim.
+
+1. Turn on the experimental
+   [containerd image store](../storage/containerd.md)
+   feature in the daemon configuration file.
+
+   > **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 . - <<EOF
+   FROM rust:latest as build
+   RUN cargo install \
+       --git https://github.com/containerd/runwasi.git \
+       --bin containerd-shim-wasmtime-v1 \
+       --root /out \
+       containerd-shim-wasmtime
+   FROM scratch
+   COPY --from=build /out/bin /
+   EOF
+   ```
+
+   Put the binary in a directory that's on your `PATH`.
+
+   ```console
+   $ mv ./containerd-shim-wasmtime-v1 /usr/local/bin
+   ```
+
+4. Run a container that uses the Wasmtime shim.
+
+   ```console
+   $ docker run --rm \
+     --runtime io.containerd.wasmtime.v1 \
+     --platform wasi/wasm32 \
+     michaelirwin244/wasm-example
+   ```