containerdにnvidiaランタイムを登録する

目標

containerdにnvidiaランタイムを登録して、TOMLの文法を検証し、CDIスペックとRuntimeClassを作成します。実際のGPUがなくても、設定の正確さは、すべて検証できます。

なぜ重要なのか

「ドライバーはインストールしたし、nvidia-smiも動くのに、コンテナではGPUが見えない」という報告の原因は、たいていランタイム登録の漏れです。そして、インターネットから拾ってきたスニペットを貼り付けたのに、何の効果もなければ、たいていはconfig versionの不一致です。セクションヘッダーが、containerdのメジャーバージョンによって、丸ごと変わります。

もう1つ、重要な判断があります。default_runtime_nameをnvidiaに変えないことです。変えると、GPUを使わないPodまで、そのランタイムを経由することになり、ランタイムの問題が、クラスター全体に広がります。RuntimeClassで、必要なワークロードだけを指定するのが、安全です。

ステップ

/etc/containerdディレクトリを作成して、/opt/fixtures/gpu-airgap/containerd/config.toml.baseを、/etc/containerd/config.tomlにコピーしてください。そして、/root/toolkit作業ディレクトリも作成してください。
config.tomlに、nvidiaランタイムのセクションを追加してください。セクションヘッダーは[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]で、runtime_type = "io.containerd.runc.v2"が入っている必要があります。
その下位に、オプションのセクションを追加してください。[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に、次の2行で書いてください。 DEFAULT=runc / WHY=runtimeclass (デフォルトのランタイムは、runcである必要があります。変えないでください。)
config.tomlをTOMLパーサーで読んで、versionの値と、登録されたランタイム名の一覧を、/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の4つがある必要があります。
/root/toolkit/report.txtを、次の5行で作成してください。 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: セクションヘッダーの引用符を忘れること。TOMLでは、ドットを含むキーは、引用符で囲む必要があります。
よくある間違い2: SystemdCgroupを、文字列"true"として書くこと。TOMLのブール値なので、引用符なしでtrueです。

基本設定ファイルを配置する

/etc/containerdディレクトリを作成して、/opt/fixtures/gpu-airgap/containerd/config.toml.baseを、/etc/containerd/config.tomlにコピーしてください。そして、/root/toolkit作業ディレクトリも作成してください。

フィクスチャに、省略された基本設定があります。実際の環境では、containerd config defaultで作成します。

nvidiaランタイムのセクションを追加する

config.tomlに、nvidiaランタイムのセクションを追加してください。セクションヘッダーは[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]で、runtime_type = "io.containerd.runc.v2"が入っている必要があります。

config version 2のCRIプラグインのパスの下の、runtimes.<名前>の形です。runtime_typeの値が核心です。

ランタイムのオプションを指定する

その下位に、オプションのセクションを追加してください。[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]の下に、BinaryName = "/usr/bin/nvidia-container-runtime"とSystemdCgroup = trueがある必要があります。

optionsは、ランタイムセクションの下位テーブルです。バイナリのパスと、cgroupドライバーの2つのキーが必要です。

デフォルトのランタイムを確認する

default_runtime_nameの値を確認して、/root/toolkit/default.txtに、次の2行で書いてください。 DEFAULT=runc / WHY=runtimeclass (デフォルトのランタイムは、runcである必要があります。変えないでください。)

default_runtime_nameは、runcである必要があります。なぜそうなのかも、一緒に記録してください。

TOMLの文法を検証する

config.tomlをTOMLパーサーで読んで、versionの値と、登録されたランタイム名の一覧を、/root/toolkit/parsed.txtに保存してください。runcとnvidiaが、両方見える必要があります。

python3.11以上には、標準ライブラリにTOMLパーサーがあります。パースに成功すれば、文法は正常です。

CDIスペックを配置する

/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の4つがある必要があります。

apiVersionとkind、metadata.name、handlerの4つが必要です。handlerは、config.tomlのランタイム名と、同じである必要があります。

登録の検証レポート

/root/toolkit/report.txtを、次の5行で作成してください。 CONFIG_VERSION=2 / RUNTIME=nvidia / RUNTIME_TYPE=io.containerd.runc.v2 / SYSTEMD_CGROUP=true / HANDLER=nvidia

値は、作成したファイルをパースして得る必要があります。パスは、絶対パスで書いてください。