Merge pull request #4799 from dvdksn/docs-cdi

docs: add documentation for CDI

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.
 

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

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
+Client:
- Version:    24.0.0
+ Version:    25.0.0
  Context:    default
  Debug Mode: false
  Plugins:
   buildx: Docker Buildx (Docker Inc.)
-    Version:  v0.10.4
+    Version:  v0.12.1
-    Path:     /usr/libexec/docker/cli-plugins/docker-buildx
+    Path:     /usr/local/libexec/docker/cli-plugins/docker-buildx
   compose: Docker Compose (Docker Inc.)
-    Version:  v2.17.2
+    Version:  v2.24.1
-    Path:     /usr/libexec/docker/cli-plugins/docker-compose
+    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
+ Server Version: 25.0.0
- Storage Driver: overlay2
+ Storage Driver: overlayfs
-  Backing Filesystem: extfs
+  driver-type: io.containerd.snapshotter.v1
-  Supports d_type: true
-  Using metacopy: false
-  Native Overlay Diff: true
-  userxattr: false
  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
+ containerd version: 71909c1814c544ac47ab91d2e8b84718e517bb99
- runc version: v1.1.5-0-gf19387a
+ runc version: v1.1.11-0-g4bccb38
  init version: de40ad0
  Security Options:
-  apparmor
   seccomp
    Profile: builtin
   cgroupns
- Kernel Version: 5.15.0-25-generic
+ Kernel Version: 6.5.11-linuxkit
- Operating System: Ubuntu 22.04 LTS
+ Operating System: Alpine Linux v3.19
  OSType: linux
- Architecture: x86_64
+ Architecture: aarch64
- CPUs: 1
+ CPUs: 10
- Total Memory: 991.7 MiB
+ Total Memory: 7.663GiB
- Name: ip-172-30-0-91.ec2.internal
+ Name: 4a7ed206a70d
- ID: 4cee4408-10d2-4e17-891c-a41736ac4536
+ 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)