nvidia-container-toolkit

NVIDIA 容器运行时工具

补充说明

NVIDIA Container Toolkit 让 Docker、containerd、Podman 在容器内访问 GPU。它包含 nvidia-ctk、runtime hook 和 CDI 支持，是 GPU 节点和 Kubernetes GPU 调度的基础。

核心步骤：安装驱动 → 安装 toolkit → 配置容器运行时 → 重启运行时 → 用 --gpus all 或 nvidia.com/gpu 验证。

常用示例

安装（Ubuntu）：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update && sudo apt install -y nvidia-container-toolkit

配置 Docker：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

配置 containerd：

sudo nvidia-ctk runtime configure --runtime=containerd
sudo systemctl restart containerd
sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place

验证：

nvidia-ctk --version
nvidia-container-cli info
docker info | grep -i runtimes

Kubernetes 节点还需要 NVIDIA device plugin，Pod 中申请 nvidia.com/gpu。

易错点与排错

• 只装了 toolkit，没有安装或加载 NVIDIA 驱动，容器内看不到 GPU。
• 配置了运行时但没有重启 Docker/containerd，配置不生效。
• containerd 的 nvidia-container-runtime 路径写错，Pod 启动失败。
• 容器内没有 --gpus all 或 NVIDIA_VISIBLE_DEVICES，GPU 不可见。
• cgroup v2 下需要正确的 no-cgroups 配置，否则挂载失败。
• 节点有 GPU 但没装 device plugin，Pod Pending。
• toolkit 版本与驱动/CUDA 不兼容，报 unsatisfied condition: cuda>=...。
• 使用 CDI 时没有生成 CDI spec，容器运行时找不到设备。