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,285 @@
+---
+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 container 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://github.com/kata-containers/kata-containers){: target="blank" rel="noopener"}
+
+## How to use alternative runtimes
+
+There are different ways you can go about selecting an alternative container
+runtime.
+
+- [Configure the default runtime](#configure-the-default-runtime)
+- [Register additional runtimes](#register-additional-runtimes)
+- [Use containerd shims](#use-a-containerd-shim)
+
+### 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": "/usr/bin/runsc"
+  }
+  ```
+
+- Using the `dockerd` CLI
+
+  ```console
+  $ dockerd --default-runtime /usr/bin/runsc
+  ```
+
+### 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",
+        "runtime-args": ["--debug"]
+      }
+    }
+  }
+  ```
+
+- Using the `dockerd` CLI
+
+  ```console
+  $ dockerd --add-runtime /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 supports runtime shims.
+Using shims, you can use alternative runtimes without having to configure or
+restart the Docker daemon.
+
+To use a containerd shim, 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.
+Fully qualified shim names take the form of `io.containerd.<shim>.<version>`.
+
+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
+```
+
+#### 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": {
+           "file-access": "shared"
+         }
+       }
+     }
+   }
+   ```
+
+2. Restart the Docker daemon.
+
+   ```console
+   # systemctl restart docker
+   ```
+
+3. Use the customized runtime using the `--runtime` flag for `docker run`.
+
+   ```console
+   $ docker run --runtime runsc ...
+   ```
+
+## 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.
+
+   Run the following commands with `sudo`, or as root.
+   This installs youki to `/usr/local/bin/youki`.
+
+   ```bash
+   #!/bin/bash
+
+   # Install the Rust toolchain
+   curl -sSf https://sh.rustup.rs | sh -s -- -y
+   source "$HOME/.cargo/env"
+
+   # Install build dependencies
+   apt-get install -y --no-install-recommends \
+       pkg-config \
+       libsystemd-dev \
+       libdbus-glib-1-dev \
+       build-essential \
+       libelf-dev \
+       libseccomp-dev \
+       libclang-dev \
+       libssl-dev
+
+   # Install youki
+   cargo install \
+       --no-track \
+       --root /usr/local \
+       --git https://github.com/containers/youki.git \
+       --features v1,v2,systemd \
+       youki
+   ```
+
+2. Register youki as a runtime for Docker by editing the Docker daemon
+   configuration file, located at `/etc/docker/daemon.json` by default.
+
+   ```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.
+
+   Run the following commands using `sudo`, or as root.
+   This installs the wasmtime containerd shim to
+   `/usr/local/bin/containerd-shim-wasmtime-v1`.
+
+   ```bash
+   #!/bin/bash
+
+   # Install the Rust toolchain
+   curl -fsSL https://sh.rustup.rs | sh -s -- -y
+   source "$HOME/.cargo/env"
+
+   # Install build dependencies
+   apt-get install -y --no-install-recommends build-essential
+
+   # Install the wasmtime
+   cargo install \
+       --git https://github.com/containerd/runwasi.git \
+       --bin containerd-shim-wasmtime-v1 \
+       --root /usr/local \
+       containerd-shim-wasmtime
+   ```
+
+4. Run a container that uses the wasmtime shim.
+
+   ```console
+   $ docker run --rm \
+     --runtime io.containerd.wasmtime.v1 \
+     --platform=wasi/wasm32 \
+     michaelirwin244/wasm-example
+   ```