docs: update the runtime configuration section

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

docs/reference/commandline/dockerd.md

@@ -396,61 +396,240 @@ Defaults to 20G.
 C:\> dockerd --storage-opt size=40G
 ```
 
-### Docker runtime execution options
+### Runtime options
 
 The Docker daemon relies on a
 [OCI](https://github.com/opencontainers/runtime-spec) compliant runtime
 (invoked via the `containerd` daemon) as its interface to the Linux
 kernel `namespaces`, `cgroups`, and `SELinux`.
 
-By default, the Docker daemon automatically starts `containerd`. If you want to
-control `containerd` startup, manually start `containerd` and pass the path to
-the `containerd` socket using the `--containerd` flag. For example:
+#### Configure container runtimes
+
+By default, the Docker daemon uses runc as a container runtime.
+You can configure the daemon to add additional runtimes.
+
+containerd shims installed on `PATH` can be used directly, without the need
+to edit the daemon's configuration.
+
+Container runtimes that don't implement containerd shims, or containerd shims
+installed outside of `PATH`, must be registered with the daemon, either via the
+configuration file or using the `--add-runtime` command line flag.
+
+For examples on how to use other container runtimes, see
+[Alternative container runtimes](https://docs.docker.com/engine/alternative-container-runtimes)
+
+##### Configure runtimes using `daemon.json`
+
+To register and configure container runtimes using the daemon's configuration
+file, add the runtimes as entries under `runtimes`:
+
+```json
+{
+  "runtimes": {
+    "<name>": {}
+  }
+}
+```
+
+The key of the entry (`<name>` in the previous example) represents the name of
+the runtime. This is the name that you reference when you run a container,
+using `docker run --runtime <name>`.
+
+The runtime entry contains an object specifying the configuration for your
+runtime. The properties of the object depends on what kind of runtime you're
+looking to register:
+
+- If the runtime implements its own containerd shim, or if you want to
+  configure the default runc shim, the object shall contain a `runtimeType`
+  field, and an optional `options` field.
+
+  ```json
+  {
+    "runtimes": {
+      "<name>": {
+        "runtimeType": "<containerd-shim>",
+        "options": {}
+      }
+    }
+  }
+  ```
+
+  See [Configure shims](#configure-containerd-shims).
+
+- If the runtime is designed to be a drop-in replacement for runc,
+  the object contains a `path` field, and an optional `runtimeArgs` field.
+
+  ```json
+  {
+    "runtimes": {
+      "<name>": {
+        "path": "/path/to/bin",
+        "runtimeArgs": ["...args"]
+      }
+    }
+  }
+  ```
+
+  See [Configure runc drop-in replacements](#configure-runc-drop-in-replacements).
+
+After changing the runtimes configuration in the configuration file,
+you must reload or restart the daemon for changes to take effect:
 
 ```console
-$ sudo dockerd --containerd /var/run/dev/docker-containerd.sock
+$ sudo systemctl reload dockerd
 ```
 
-Runtimes can be registered with the daemon either via the
-configuration file or using the `--add-runtime` command line argument.
+###### Configure containerd shims
 
-The following is an example adding 2 runtimes via the configuration:
+If the runtime that you want to register implements a containerd shim,
+or if you want to configure the default runc shim,
+use the following format for the runtime entry:
 
 ```json
 {
-  "default-runtime": "runc",
   "runtimes": {
-    "custom": {
-      "path": "/usr/local/bin/my-runc-replacement",
-      "runtimeArgs": [
-        "--debug"
-      ]
+    "<name>": {
+      "runtimeType": "",
+      "options": {}
+    }
+  }
+}
+```
+
+`runtimeType` refers to either:
+
+- A fully qualified name of a containerd shim.
+
+  The fully qualified name of a shim is the same as `runtime_type` used in
+  CRI containerd configuration. For example, `io.containerd.runsc.v1`.
+
+- The path of a containerd shim binary.
+
+  This option is useful if you installed the containerd shim binary outside of
+  `PATH`.
+
+`options` is optional. It lets you specify the runtime configuration that you
+want to use for the shim. The configuration parameters that you can specify in
+`options` depends on the runtime you're registering. For most shims,
+the supported configuration options are `TypeUrl` and `ConfigPath`:
+
+```json
+{
+  "runtimes": {
+    "<name>": {
+      "runtimeType": "<containerd-shim>",
+      "options": {
+        "TypeUrl": "<containerd-shim-typeUrl>",
+        "ConfigPath": "/path/to/config.toml",
+      }
+    }
+  }
+}
+```
+
+You can configure multiple runtimes using the same runtimeType. For example:
+
+```json
+{
+  "runtimes": {
+    "gvisor-foo": {
+      "runtimeType": "io.containerd.runsc.v1",
+      "options": {
+        "TypeUrl": "io.containerd.runsc.v1.options",
+        "ConfigPath": "/etc/containerd/runsc-foo.toml"
+      }
     },
-    "runc": {
-      "path": "runc"
+    "gvisor-bar": {
+      "runtimeType": "io.containerd.runsc.v1",
+      "options": {
+        "TypeUrl": "io.containerd.runsc.v1.options",
+        "ConfigPath": "/etc/containerd/runsc-bar.toml"
+      }
     }
   }
 }
 ```
 
-This is the same example via the command line:
+If you want to use the runc shims with custom configuration, note that the
+`options` field takes a special set of configuration parameters when used with
+runc shims. For more information about runc parameters, refer to the runc
+configuration section in
+[CRI Plugin Config Guide](https://github.com/containerd/containerd/blob/main/docs/cri/config.md#full-configuration).
+
+###### Configure runc drop-in replacements
+
+If the runtime that you want to register can act as a drop-in replacement for
+runc, use the following format for the runtime entry:
+
+```json
+{
+  "runtimes": {
+    "<name>": {
+      "path": "/path/to/binary",
+      "runtimeArgs": ["...args"]
+    }
+  }
+}
+```
+
+Entries with this format use the default containerd runc shim to invoke a
+custom runtime binary, with optional CLI args. For an example, see
+[Alternative container runtimes > youki](https://docs.docker.com/engine/alternative-runtimes/#youki)
+
+##### Register runtimes using the CLI
+
+You can use the `--add-runtime` CLI flag to register runtimes on daemon startup.
+
+You can specify either the name of a fully qualified containerd runtime shim,
+or the name of a registered runtime. The executable must be installed on `PATH`.
+
+The following example adds a runtime named `youki`:
 
 ```console
-$ sudo dockerd --add-runtime runc=runc --add-runtime custom=/usr/local/bin/my-runc-replacement
+$ sudo dockerd --add-runtime youki=/usr/bin/youki
 ```
 
 > **Note**
 >
 > Defining runtime arguments via the command line is not supported.
 
-#### Options for the runtime
+##### Configure the default container runtime
+
+You can specify either the name of a fully qualified containerd runtime shim,
+or the name of a registered runtime. The executable must be installed on `PATH`.
+
+The following examples set the gVisor shim as the default runtime:
+
+- Using the daemon configuration file
+
+  ```json
+  {
+    "default-runtime": "io.containerd.runsc.v1"
+  }
+  ```
+
+- Using the `dockerd` CLI
+
+  ```console
+  $ dockerd --default-runtime io.containerd.runsc.v1
+  ```
+
+#### Use a manually controlled containerd daemon
 
-You can configure the runtime using options specified
-with the `--exec-opt` flag. All the flag's options have the `native` prefix. A
-single `native.cgroupdriver` option is available.
+By default, the Docker daemon automatically starts `containerd`. If you want to
+control `containerd` startup, manually start `containerd` and pass the path to
+the `containerd` socket using the `--containerd` flag. For example:
 
-The `native.cgroupdriver` option specifies the management of the container's
-cgroups. You can only specify `cgroupfs` or `systemd`. If you specify
+```console
+$ sudo dockerd --containerd /var/run/dev/docker-containerd.sock
+```
+
+#### Configure cgroup driver
+
+You can configure how the runtime should manage container cgroups, using the
+`--exec-opt native.cgroupdriver` CLI flag.
+
+You can only specify `cgroupfs` or `systemd`. If you specify
 `systemd` and it is not available, the system errors out. If you omit the
 `native.cgroupdriver` option,` cgroupfs` is used on cgroup v1 hosts, `systemd`
 is used on cgroup v2 hosts with systemd available.
@@ -463,16 +642,19 @@ $ sudo dockerd --exec-opt native.cgroupdriver=systemd
 
 Setting this option applies to all containers the daemon launches.
 
-Also Windows Container makes use of `--exec-opt` for special purpose. Docker user
-can specify default container isolation technology with this, for example:
+#### Configure container isolation technology (Windows)
+
+For Windows containers, you can specify the default container isolation
+technology to use, using the `--exec-opt isolation` flag. 
+
+The following example makes `hyperv` the default isolation technology:
 
 ```console
 > dockerd --exec-opt isolation=hyperv
 ```
 
-Will make `hyperv` the default isolation technology on Windows. If no isolation
-value is specified on daemon start, on Windows client, the default is
-`hyperv`, and on Windows server, the default is `process`.
+If no isolation value is specified on daemon start, on Windows client,
+the default is `hyperv`, and on Windows server, the default is `process`.
 
 ### Daemon DNS options