docs: add documentation for CDI

- Add section about cdi-spec-dirs daemon configuration - Add subsection about cdi in --device section for docker run - Update `docker info` output example Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
2024-01-18 13:24:23 +01:00 · 2024-01-18 13:24:23 +01:00 · 852d198bb5
parent e758fe5a7f
commit 852d198bb5
3 changed files with 97 additions and 27 deletions
--- a/docs/reference/commandline/container_run.md
+++ b/docs/reference/commandline/container_run.md
@ -858,6 +858,38 @@ PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.micro
 > The `--device` option is only supported on process-isolated Windows containers,
 > and produces an error if the container isolation is `hyperv`.

+#### CDI devices
+
+> **Note**
+>
+> This is experimental feature and as such doesn't represent a stable API.
+
+Container Device Interface (CDI) is a
+[standardized](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md)
+mechanism for container runtimes to create containers which are able to
+interact with third party devices.
+
+With CDI, device configurations are defined using a JSON file. In addition to
+enabling the container to interact with the device node, it also lets you
+specify additional configuration for the device, such as kernel modules, host
+libraries, and environment variables.
+
+You can reference a CDI device with the `--device` flag using the
+fully-qualified name of the device, as shown in the following example:
+
+```console
+$ docker run --device=vendor.com/class=device-name --rm -it ubuntu
+```
+
+This starts an `ubuntu` container with access to the specified CDI device,
+`vendor.com/class=device-name`, assuming that:
+
+- A valid CDI specification (JSON file) for the requested device is available
+  on the system running the daemon, in one of the configured CDI specification
+  directories.
+- The CDI feature has been enabled on the daemon side, see [Enable CDI
+  devices](dockerd.md#enable-cdi-devices).
+
 ### <a name="attach"></a> Attach to STDIN/STDOUT/STDERR (-a, --attach)

 The `--attach` (or `-a`) flag tells `docker run` to bind to the container's
@ -1016,6 +1048,11 @@ the required device when it is added.
 The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to
 install the [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/).

+> **Note**
+>
+> You can also specify a GPU as a CDI device with the `--device` flag, see
+> [CDI devices](#cdi-devices).
+
 Read [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/)
 for more information.

--- a/docs/reference/commandline/dockerd.md
+++ b/docs/reference/commandline/dockerd.md
@ -29,6 +29,7 @@ Options:
      --authorization-plugin list             Authorization plugins to load
      --bip string                            Specify network bridge IP
  -b, --bridge string                         Attach containers to a network bridge
+      --cdi-spec-dir list                     CDI specification directories to use
      --cgroup-parent string                  Set parent cgroup for all containers
      --config-file string                    Daemon configuration file (default "/etc/docker/daemon.json")
      --containerd string                     containerd grpc address
@ -854,6 +855,44 @@ $ docker run -it --add-host host.docker.internal:host-gateway \
 PING host.docker.internal (192.0.2.0): 56 data bytes
 ```

+### Enable CDI devices
+
+> **Note**
+>
+> This is experimental feature and as such doesn't represent a stable API.
+>
+> This feature isn't enabled by default. To this feature, set `features.cdi` to
+> `true` in the `daemon.json` configuration file.
+
+Container Device Interface (CDI) is a
+[standardized](https://github.com/cncf-tags/container-device-interface/blob/main/SPEC.md)
+mechanism for container runtimes to create containers which are able to
+interact with third party devices.
+
+The Docker daemon supports running containers with CDI devices if the requested
+device specifications are available on the filesystem of the daemon.
+
+The default specification directors are:
+
+- `/etc/cdi/` for static CDI Specs
+- `/var/run/cdi` for generated CDI Specs
+
+Alternatively, you can set custom locations for CDI specifications using the
+`cdi-spec-dirs` option in the `daemon.json` configuration file, or the
+`--cdi-spec-dir` flag for the `dockerd` CLI.
+
+```json
+{
+  "features": {
+     "cdi": true
+  },
+  "cdi-spec-dirs": ["/etc/cdi/", "/var/run/cdi"]
+}
+```
+
+When CDI is enabled for a daemon, you can view the configured CDI specification
+directories using the `docker info` command.
+
 ### Miscellaneous options

 IP masquerading uses address translation to allow containers without a public
--- a/docs/reference/commandline/system_info.md
+++ b/docs/reference/commandline/system_info.md
@ -47,17 +47,17 @@ information about the `overlay2` storage driver is shown:
 ```console
 $ docker info

-Client: Docker Engine - Community
- Version:    24.0.0
+Client:
+ Version:    25.0.0
 Context:    default
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
-    Version:  v0.10.4
-    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
+    Version:  v0.12.1
+    Path:     /usr/local/libexec/docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
-    Version:  v2.17.2
-    Path:     /usr/libexec/docker/cli-plugins/docker-compose
+    Version:  v2.24.1
+    Path:     /usr/local/libexec/docker/cli-plugins/docker-compose

 Server:
 Containers: 14
@ -65,15 +65,11 @@ Server:
  Paused: 1
  Stopped: 10
 Images: 52
- Server Version: 23.0.3
- Storage Driver: overlay2
-  Backing Filesystem: extfs
-  Supports d_type: true
-  Using metacopy: false
-  Native Overlay Diff: true
-  userxattr: false
+ Server Version: 25.0.0
+ Storage Driver: overlayfs
+  driver-type: io.containerd.snapshotter.v1
 Logging Driver: json-file
- Cgroup Driver: systemd
+ Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
@ -83,33 +79,31 @@ Server:
  /etc/cdi
  /var/run/cdi
 Swarm: inactive
- Runtimes: io.containerd.runc.v2 runc
+ Runtimes: runc io.containerd.runc.v2
 Default Runtime: runc
 Init Binary: docker-init
- containerd version: 2806fc1057397dbaeefbea0e4e17bddfbd388f38
- runc version: v1.1.5-0-gf19387a
+ containerd version: 71909c1814c544ac47ab91d2e8b84718e517bb99
+ runc version: v1.1.11-0-g4bccb38
 init version: de40ad0
 Security Options:
-  apparmor
  seccomp
   Profile: builtin
  cgroupns
- Kernel Version: 5.15.0-25-generic
- Operating System: Ubuntu 22.04 LTS
+ Kernel Version: 6.5.11-linuxkit
+ Operating System: Alpine Linux v3.19
 OSType: linux
- Architecture: x86_64
- CPUs: 1
- Total Memory: 991.7 MiB
- Name: ip-172-30-0-91.ec2.internal
- ID: 4cee4408-10d2-4e17-891c-a41736ac4536
+ Architecture: aarch64
+ CPUs: 10
+ Total Memory: 7.663GiB
+ Name: 4a7ed206a70d
+ ID: c20f7230-59a2-4824-a2f4-fda71c982ee6
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
- Username: gordontheturtle
 Experimental: false
 Insecure Registries:
-  myinsecurehost:5000
  127.0.0.0/8
 Live Restore Enabled: false
+ Product License: Community Engine
 ```

 ### <a name="format"></a> Format the output (--format)