把 nvidia 运行时注册到 containerd

目标

在 containerd 中注册 nvidia runtime，验证 TOML 语法，并编写 CDI spec 和 RuntimeClass。即使没有真实 GPU，也能完整验证配置的准确性。

为什么重要

“驱动已经安装，nvidia-smi 也能运行，但容器中看不到 GPU”这类问题，原因通常是遗漏 runtime 注册。如果从网上复制的片段没有任何效果，大多是因为 config version 不匹配：section header 会随 containerd 主版本整体改变。

还有一项重要判断：不要把 default_runtime_name 改为 nvidia。否则，连不使用 GPU 的 Pod 也会经过该 runtime，runtime 故障将扩散到整个集群。更安全的做法是通过 RuntimeClass 只为有需要的工作负载指定它。

步骤

创建 /etc/containerd 目录，将 /opt/fixtures/gpu-airgap/containerd/config.toml.base 复制为 /etc/containerd/config.toml。同时创建 /root/toolkit 工作目录。
在 config.toml 中添加 nvidia runtime section。section header 必须是 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]，并包含 runtime_type = "io.containerd.runc.v2"。
在其下添加 options section。在 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options] 下必须包含 BinaryName = "/usr/bin/nvidia-container-runtime" 和 SystemdCgroup = true。
检查 default_runtime_name 的值，并按以下两行写入 /root/toolkit/default.txt。 DEFAULT=runc / WHY=runtimeclass （默认 runtime 必须是 runc，不要修改。）
使用 TOML parser 读取 config.toml，将 version 值和已注册的 runtime 名称列表保存到 /root/toolkit/parsed.txt。必须同时显示 runc 和 nvidia。
确认 /etc/cdi/nvidia.yaml 存在且包含 kind: nvidia.com/gpu；若不存在则创建。然后将顶层键列表保存到 /root/toolkit/cdi-keys.txt。
编写 /root/toolkit/runtimeclass.yaml。必须包含 apiVersion: node.k8s.io/v1、kind: RuntimeClass、metadata.name: nvidia、handler: nvidia 四项。
按以下 5 行创建 /root/toolkit/report.txt。 CONFIG_VERSION=2 / RUNTIME=nvidia / RUNTIME_TYPE=io.containerd.runc.v2 / SYSTEMD_CGROUP=true / HANDLER=nvidia

参考

TOML 解析可以采用 python3 -c "import tomllib;d=tomllib.load(open('/etc/containerd/config.toml','rb'));print(d['version'])" 的形式。
在真实环境中，nvidia-ctk runtime configure --runtime=containerd --set-as-default=false 可代替第 2～3 步。
RuntimeClass 的 handler 必须与 config.toml 中的 runtimes.<이름> 完全一致。若不一致，Pod 会显示 RunContainerError。
常见错误 1：遗漏 section header 中的引号。在 TOML 中，包含点号的键必须用引号包围。
常见错误 2：将 SystemdCgroup 写成字符串 "true"。它是 TOML boolean，应写为不带引号的 true。

放置基础配置文件

创建 /etc/containerd 目录，将 /opt/fixtures/gpu-airgap/containerd/config.toml.base 复制为 /etc/containerd/config.toml。同时创建 /root/toolkit 工作目录。

fixture 中有精简的基础配置。真实环境中可通过 containerd config default 生成。

添加 nvidia runtime section

在 config.toml 中添加 nvidia runtime section。section header 必须是 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]，并包含 runtime_type = "io.containerd.runc.v2"。

在 config version 2 的 CRI plugin 路径下采用 runtimes.<名称> 的形式，关键是 runtime_type 的值。

指定 runtime 选项

在其下添加 options section。在 [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options] 下必须包含 BinaryName = "/usr/bin/nvidia-container-runtime" 和 SystemdCgroup = true。

options 是 runtime section 的子表，需要 binary 路径和 cgroup driver 两个键。

检查默认 runtime

检查 default_runtime_name 的值，并按以下两行写入 /root/toolkit/default.txt。 DEFAULT=runc / WHY=runtimeclass （默认 runtime 必须是 runc，不要修改。）

default_runtime_name 必须为 runc，同时记录这样设置的原因。

验证 TOML 语法

使用 TOML parser 读取 config.toml，将 version 值和已注册的 runtime 名称列表保存到 /root/toolkit/parsed.txt。必须同时显示 runc 和 nvidia。

Python 3.11 及更高版本的标准库包含 TOML parser。能够成功解析就表示语法正确。

放置 CDI spec

确认 /etc/cdi/nvidia.yaml 存在且包含 kind: nvidia.com/gpu；若不存在则创建。然后将顶层键列表保存到 /root/toolkit/cdi-keys.txt。

结构与前一课程创建的文件相同。本步骤只检查放置路径和最少必需键。

编写 RuntimeClass

编写 /root/toolkit/runtimeclass.yaml。必须包含 apiVersion: node.k8s.io/v1、kind: RuntimeClass、metadata.name: nvidia、handler: nvidia 四项。

需要 apiVersion、kind、metadata.name 和 handler 四项。handler 必须与 config.toml 中的 runtime 名称一致。

注册验证报告

按以下 5 行创建 /root/toolkit/report.txt。 CONFIG_VERSION=2 / RUNTIME=nvidia / RUNTIME_TYPE=io.containerd.runc.v2 / SYSTEMD_CGROUP=true / HANDLER=nvidia

这些值必须通过解析已编写的文件获得。路径请写为绝对路径。