容器裝置介面 (CDI)
目錄
容器設備介面 (CDI) 是一項旨在標準化設備（如 GPU、FPGA 和其他硬體加速器）如何暴露給容器並由其使用之規範。其目的是為容器化環境中的硬體設備使用提供更一致且更安全的機制，解決與設備特定設定和組態相關的挑戰。
除了使容器能夠與設備節點互動外，CDI 還允許您為設備指定額外的組態，例如環境變數、主機掛載（如共用物件）以及可執行鉤子 (hooks)。
入門指南
要開始使用 CDI，您需要建立一個相容的環境。這包括安裝 Docker v27+ 並設定 CDI，以及 Buildx v0.22+。
您還需要使用 JSON 或 YAML 檔案建立設備規範，並將其放置於以下任一位置：
/etc/cdi/var/run/cdi/etc/buildkit/cdi
注意如果您直接使用 BuildKit，可以透過在
buildkitd.toml組態檔案的cdi區段中設定specDirs選項來更改位置。如果您使用帶有docker驅動程式的 Docker Daemon 進行建構，請參閱設定 CDI 設備文件。
注意如果您在 WSL 上建立容器建構器，則需要確保已安裝 Docker Desktop 並啟用 WSL 2 GPU 半虛擬化 (Paravirtualization)。若要在容器中掛載 WSL 函式庫，也需要 Buildx v0.27+。
使用簡單的 CDI 規範進行建構
讓我們從一個簡單的 CDI 規範開始，將環境變數注入建構環境中，並將其寫入 /etc/cdi/foo.yaml：
/etc/cdi/foo.yaml
cdiVersion: "0.6.0"
kind: "vendor1.com/device"
devices:
- name: foo
containerEdits:
env:
- FOO=injected檢查 default 建構器以驗證 vendor1.com/device 是否被偵測為一個設備：
$ docker buildx inspect
Name: default
Driver: docker
Nodes:
Name: default
Endpoint: default
Status: running
BuildKit version: v0.23.2
Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/amd64/v4, linux/386
Labels:
org.mobyproject.buildkit.worker.moby.host-gateway-ip: 172.17.0.1
Devices:
Name: vendor1.com/device=foo
Automatically allowed: false
GC Policy rule#0:
All: false
Filters: type==source.local,type==exec.cachemount,type==source.git.checkout
Keep Duration: 48h0m0s
Max Used Space: 658.9MiB
GC Policy rule#1:
All: false
Keep Duration: 1440h0m0s
Reserved Space: 4.657GiB
Max Used Space: 953.7MiB
Min Free Space: 2.794GiB
GC Policy rule#2:
All: false
Reserved Space: 4.657GiB
Max Used Space: 953.7MiB
Min Free Space: 2.794GiB
GC Policy rule#3:
All: true
Reserved Space: 4.657GiB
Max Used Space: 953.7MiB
Min Free Space: 2.794GiB
現在讓我們建立一個 Dockerfile 來使用此設備：
# syntax=docker/dockerfile:1-labs
FROM busybox
RUN --device=vendor1.com/device \
env | grep ^FOO=這裡我們使用 RUN --device 指令並設定 vendor1.com/device，這會請求規範中第一個可用的設備。在此情況下，它使用 foo，即 /etc/cdi/foo.yaml 中的第一個設備。
注意
RUN --device指令自 Dockerfile 前端 v1.14.0-labs 起僅在labs頻道中提供，尚未在穩定語法中可用。
現在讓我們建構此 Dockerfile：
$ docker buildx build .
[+] Building 0.4s (5/5) FINISHED docker:default
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 155B 0.0s
=> resolve image config for docker-image://docker/dockerfile:1-labs 0.1s
=> CACHED docker-image://docker/dockerfile:1-labs@sha256:9187104f31e3a002a8a6a3209ea1f937fb7486c093cbbde1e14b0fa0d7e4f1b5 0.0s
=> [internal] load metadata for docker.io/library/busybox:latest 0.1s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
ERROR: failed to build: failed to solve: failed to load LLB: device vendor1.com/device=foo is requested by the build but not allowed
它會失敗，因為如上方 buildx inspect 輸出所示，該建構並未自動允許設備 vendor1.com/device=foo。
Devices:
Name: vendor1.com/device=foo
Automatically allowed: false若要允許該設備，您可以在 docker buildx build 指令中使用 --allow 旗標：
$ docker buildx build --allow device .
或者，您可以在 CDI 規範中設定 org.mobyproject.buildkit.device.autoallow 註解，以自動為所有建構允許該設備。
/etc/cdi/foo.yaml
cdiVersion: "0.6.0"
kind: "vendor1.com/device"
devices:
- name: foo
containerEdits:
env:
- FOO=injected
annotations:
org.mobyproject.buildkit.device.autoallow: true現在再次使用 --allow device 旗標執行建構：
$ docker buildx build --progress=plain --allow device .
#0 building with "default" instance using docker driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 159B done
#1 DONE 0.0s
#2 resolve image config for docker-image://docker/dockerfile:1-labs
#2 DONE 0.1s
#3 docker-image://docker/dockerfile:1-labs@sha256:9187104f31e3a002a8a6a3209ea1f937fb7486c093cbbde1e14b0fa0d7e4f1b5
#3 CACHED
#4 [internal] load metadata for docker.io/library/busybox:latest
#4 DONE 0.1s
#5 [internal] load .dockerignore
#5 transferring context: 2B done
#5 DONE 0.0s
#6 [1/2] FROM docker.io/library/busybox:latest@sha256:f85340bf132ae937d2c2a763b8335c9bab35d6e8293f70f606b9c6178d84f42b
#6 CACHED
#7 [2/2] RUN --device=vendor1.com/device env | grep ^FOO=
#7 0.155 FOO=injected
#7 DONE 0.2s
建構成功，輸出顯示 FOO 環境變數已按照 CDI 規範的定義注入到建構環境中。
設定具備 GPU 支援的容器建構器
在本節中，我們將向您展示如何設定使用 NVIDIA GPU 的容器建構器。自 Buildx v0.22 起，當建立新的容器建構器時，如果主機的核心安裝了 GPU 驅動程式，GPU 請求會自動新增至容器建構器中。這類似於在 docker run 指令中使用 --gpus=all。
注意我們特別製作了一個 BuildKit 映像檔，因為當前的 BuildKit 發行版映像檔是基於 Alpine，不支援 NVIDIA 驅動程式。以下映像檔基於 Ubuntu，它安裝了 NVIDIA 客戶端函式庫，並在建構期間請求設備時，於容器建構器中為您的 GPU 產生 CDI 規範。此映像檔暫時託管於 Docker Hub，路徑為
crazymax/buildkit:v0.23.2-ubuntu-nvidia。
現在，讓我們使用 Buildx 建立一個名為 gpubuilder 的容器建構器：
$ docker buildx create --name gpubuilder --driver-opt "image=crazymax/buildkit:v0.23.2-ubuntu-nvidia" --bootstrap
#1 [internal] booting buildkit
#1 pulling image crazymax/buildkit:v0.23.2-ubuntu-nvidia
#1 pulling image crazymax/buildkit:v0.23.2-ubuntu-nvidia 1.0s done
#1 creating container buildx_buildkit_gpubuilder0
#1 creating container buildx_buildkit_gpubuilder0 8.8s done
#1 DONE 9.8s
gpubuilder
讓我們檢查此建構器：
$ docker buildx inspect gpubuilder
Name: gpubuilder
Driver: docker-container
Last Activity: 2025-07-10 08:18:09 +0000 UTC
Nodes:
Name: gpubuilder0
Endpoint: unix:///var/run/docker.sock
Driver Options: image="crazymax/buildkit:v0.23.2-ubuntu-nvidia"
Status: running
BuildKit daemon flags: --allow-insecure-entitlement=network.host
BuildKit version: v0.23.2
Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
Labels:
org.mobyproject.buildkit.worker.executor: oci
org.mobyproject.buildkit.worker.hostname: d6aa9cbe8462
org.mobyproject.buildkit.worker.network: host
org.mobyproject.buildkit.worker.oci.process-mode: sandbox
org.mobyproject.buildkit.worker.selinux.enabled: false
org.mobyproject.buildkit.worker.snapshotter: overlayfs
Devices:
Name: nvidia.com/gpu
On-Demand: true
GC Policy rule#0:
All: false
Filters: type==source.local,type==exec.cachemount,type==source.git.checkout
Keep Duration: 48h0m0s
Max Used Space: 488.3MiB
GC Policy rule#1:
All: false
Keep Duration: 1440h0m0s
Reserved Space: 9.313GiB
Max Used Space: 93.13GiB
Min Free Space: 188.1GiB
GC Policy rule#2:
All: false
Reserved Space: 9.313GiB
Max Used Space: 93.13GiB
Min Free Space: 188.1GiB
GC Policy rule#3:
All: true
Reserved Space: 9.313GiB
Max Used Space: 93.13GiB
Min Free Space: 188.1GiB
我們可以看到 nvidia.com/gpu 供應商已被偵測為建構器中的一個設備，這表示驅動程式已被偵測到。
您可以選擇使用 nvidia-smi 檢查容器中是否可以使用 NVIDIA GPU 設備：
$ docker exec -it buildx_buildkit_gpubuilder0 nvidia-smi -L
GPU 0: Tesla T4 (UUID: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84)
使用 GPU 支援進行建構
讓我們建立一個簡單的 Dockerfile 來使用 GPU 設備：
# syntax=docker/dockerfile:1-labs
FROM ubuntu
RUN --device=nvidia.com/gpu nvidia-smi -L現在使用我們剛建立的 gpubuilder 建構器執行建構：
$ docker buildx --builder gpubuilder build --progress=plain .
#0 building with "gpubuilder" instance using docker-container driver
...
#7 preparing device nvidia.com/gpu
#7 0.000 > apt-get update
...
#7 4.872 > apt-get install -y gpg
...
#7 10.16 Downloading NVIDIA GPG key
#7 10.21 > apt-get update
...
#7 12.15 > apt-get install -y --no-install-recommends nvidia-container-toolkit-base
...
#7 17.80 time="2025-04-15T08:58:16Z" level=info msg="Generated CDI spec with version 0.8.0"
#7 DONE 17.8s
#8 [2/2] RUN --device=nvidia.com/gpu nvidia-smi -L
#8 0.527 GPU 0: Tesla T4 (UUID: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84)
#8 DONE 1.6s
您可能已經注意到，步驟 #7 正在準備 nvidia.com/gpu 設備，透過安裝客戶端函式庫和工具組來產生 GPU 的 CDI 規範。
然後在容器中透過使用該 GPU 設備執行 nvidia-smi -L 指令。輸出顯示了 GPU 的 UUID。
您可以使用以下指令檢查容器建構器中產生的 CDI 規範：
$ docker exec -it buildx_buildkit_gpubuilder0 cat /etc/cdi/nvidia.yaml
對於此處使用的 EC2 執行個體 g4dn.xlarge，看起來如下：
cdiVersion: 0.6.0
containerEdits:
deviceNodes:
- path: /dev/nvidia-modeset
- path: /dev/nvidia-uvm
- path: /dev/nvidia-uvm-tools
- path: /dev/nvidiactl
env:
- NVIDIA_VISIBLE_DEVICES=void
hooks:
- args:
- nvidia-cdi-hook
- create-symlinks
- --link
- ../libnvidia-allocator.so.1::/usr/lib/x86_64-linux-gnu/gbm/nvidia-drm_gbm.so
hookName: createContainer
path: /usr/bin/nvidia-cdi-hook
- args:
- nvidia-cdi-hook
- create-symlinks
- --link
- libcuda.so.1::/usr/lib/x86_64-linux-gnu/libcuda.so
hookName: createContainer
path: /usr/bin/nvidia-cdi-hook
- args:
- nvidia-cdi-hook
- enable-cuda-compat
- --host-driver-version=570.133.20
hookName: createContainer
path: /usr/bin/nvidia-cdi-hook
- args:
- nvidia-cdi-hook
- update-ldcache
- --folder
- /usr/lib/x86_64-linux-gnu
hookName: createContainer
path: /usr/bin/nvidia-cdi-hook
mounts:
- containerPath: /run/nvidia-persistenced/socket
hostPath: /run/nvidia-persistenced/socket
options:
- ro
- nosuid
- nodev
- bind
- noexec
- containerPath: /usr/bin/nvidia-cuda-mps-control
hostPath: /usr/bin/nvidia-cuda-mps-control
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/bin/nvidia-cuda-mps-server
hostPath: /usr/bin/nvidia-cuda-mps-server
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/bin/nvidia-debugdump
hostPath: /usr/bin/nvidia-debugdump
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/bin/nvidia-persistenced
hostPath: /usr/bin/nvidia-persistenced
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/bin/nvidia-smi
hostPath: /usr/bin/nvidia-smi
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libcuda.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libcuda.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libcudadebugger.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libcudadebugger.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-allocator.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-allocator.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-cfg.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-cfg.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-gpucomp.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-gpucomp.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-ml.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-nscq.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-nscq.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-nvvm.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-nvvm.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-opencl.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-opencl.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11-openssl3.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11-openssl3.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-pkcs11.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /usr/lib/x86_64-linux-gnu/libnvidia-ptxjitcompiler.so.570.133.20
hostPath: /usr/lib/x86_64-linux-gnu/libnvidia-ptxjitcompiler.so.570.133.20
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /lib/firmware/nvidia/570.133.20/gsp_ga10x.bin
hostPath: /lib/firmware/nvidia/570.133.20/gsp_ga10x.bin
options:
- ro
- nosuid
- nodev
- bind
- containerPath: /lib/firmware/nvidia/570.133.20/gsp_tu10x.bin
hostPath: /lib/firmware/nvidia/570.133.20/gsp_tu10x.bin
options:
- ro
- nosuid
- nodev
- bind
devices:
- containerEdits:
deviceNodes:
- path: /dev/nvidia0
name: "0"
- containerEdits:
deviceNodes:
- path: /dev/nvidia0
name: GPU-6cf00fa7-59ac-16f2-3e83-d24ccdc56f84
- containerEdits:
deviceNodes:
- path: /dev/nvidia0
name: all
kind: nvidia.com/gpu恭喜您完成了第一次使用 BuildKit 和 CDI 的 GPU 設備建構。