NVIDIA k8s-device-plugin 部署问题排查与解决方案

问题背景

在 Kubernetes 集群中部署 NVIDIA GPU 设备插件时，经常会遇到节点无法正确识别 GPU 资源的问题。本文将以一个实际案例为基础，详细介绍如何排查和解决这类问题。

环境配置

硬件环境

• 服务器型号：Dell 服务器
• GPU 配置：4 块 NVIDIA Tesla T4 显卡
• 节点类型：Kubernetes 单节点集群（同时作为控制平面和工作节点）

软件环境

• 操作系统：Ubuntu 24.04.2 LTS
• 内核版本：6.8.0-58-generic
• Kubernetes 版本：v1.32.2
• 容器运行时：containerd 2.0.3
• NVIDIA 驱动版本：570.133.20
• CUDA 版本：12.8

问题现象

在完成 NVIDIA 设备插件部署后，通过 kubectl describe node 命令检查节点资源时，发现 GPU 资源未被正确识别：

Capacity:
  cpu:                48
  ephemeral-storage:  227966388Ki
  hugepages-1Gi:      0
  hugepages-2Mi:      0
  memory:             394810384Ki
  pods:               110

同时，NVIDIA 设备插件容器日志中显示以下错误信息：

Incompatible strategy detected auto
If this is a GPU node, did you configure the NVIDIA Container Toolkit?

排查过程

1. 基础环境检查

首先确认基础环境配置正确：

• 通过 lspci 命令确认 GPU 设备已被系统识别
• 使用 nvidia-smi 命令确认驱动安装正常
• 检查 Kubernetes 节点状态正常

2. 容器运行时配置检查

重点检查 containerd 的配置文件 /etc/containerd/config.toml，发现配置中存在一个关键问题：

[plugins."io.containerd.cri.v1.runtime".containerd.runtimes.nvidia.options]
  BinaryName = "/usr/bin/nvidia-container-runtime"
  binaryName = "/usr/local/bin/runc"  # 这一行是冗余且错误的配置
  systemdCgroup = true

这个配置文件中同时指定了 BinaryName 和 binaryName，其中 binaryName 错误地指向了标准的 runc 路径，而不是 NVIDIA 容器运行时。

3. RuntimeClass 配置

在尝试通过 Helm 安装设备插件时，遇到了 RuntimeClass 不存在的错误。这是因为 Kubernetes 需要明确知道如何使用 NVIDIA 运行时来运行容器。

解决方案是创建以下 RuntimeClass 资源：

apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia

解决方案

1. 修正 containerd 配置

删除冗余的 binaryName 配置行，确保 NVIDIA 运行时配置简洁正确：

[plugins."io.containerd.cri.v1.runtime".containerd.runtimes.nvidia.options]
  BinaryName = "/usr/bin/nvidia-container-runtime"
  systemdCgroup = true

修改后需要重启 containerd 服务：

sudo systemctl restart containerd

2. 正确安装设备插件

使用 Helm 安装 NVIDIA 设备插件时，确保指定正确的运行时类：

runtimeClassName: nvidia

3. 验证结果

完成上述修改后，节点正确显示了 GPU 资源：

Capacity:
  cpu:                48
  ephemeral-storage:  227966388Ki
  hugepages-1Gi:      0
  hugepages-2Mi:      0
  memory:             394810384Ki
  nvidia.com/gpu:     4
  pods:               110

经验总结

1. 配置文件的准确性至关重要：即使是看似微小的配置错误（如大小写不一致或冗余配置）也可能导致整个功能失效。

2. 运行时配置的完整性：在 Kubernetes 中使用特殊容器运行时（如 NVIDIA 运行时）时，需要同时配置容器引擎和 Kubernetes 的 RuntimeClass。

3. 排查顺序建议：

   • 首先确认硬件和驱动层正常工作
   • 然后检查容器运行时配置
   • 最后验证 Kubernetes 层面的资源发现

4. 日志分析：设备插件的日志通常会提供明确的错误原因和解决建议，应作为排查的第一手资料。

通过系统性地排查和验证每个环节，可以确保 NVIDIA GPU 资源在 Kubernetes 集群中被正确识别和管理，为后续的 AI/ML 工作负载提供可靠的硬件支持。