NVIDIA k8s-device-plugin 常见问题：libnvidia-ml.so.1 加载失败的解决方案

问题背景

在使用 NVIDIA k8s-device-plugin 时，许多用户遇到了"could not load NVML library: libnvidia-ml.so.1"的错误。这个问题通常出现在 Kubernetes 集群中尝试使用 NVIDIA GPU 资源时，设备插件无法正常加载 NVML 库。

错误表现

设备插件日志中会出现如下关键错误信息：

Detected non-NVML platform: could not load NVML library: libnvidia-ml.so.1: cannot open shared object file: No such file or directory
Detected non-Tegra platform: /sys/devices/soc0/family file not found
Incompatible platform detected

根本原因分析

这个问题的核心在于容器运行时环境无法访问到宿主机上的 NVIDIA 驱动库文件。具体可能由以下几个因素导致：

1. 容器运行时配置不正确：containerd 或 Docker 的运行时配置没有正确指向 NVIDIA 容器运行时
2. 环境隔离问题：在 Minikube 或 Docker Desktop 等虚拟化环境中，GPU 资源没有正确透传给容器
3. 驱动安装不完整：虽然 nvidia-smi 可以工作，但容器运行时需要的组件没有正确安装
4. 路径问题：容器内无法访问到宿主机上的 libnvidia-ml.so.1 库文件

解决方案

1. 验证基础环境

首先确保宿主机环境满足以下条件：

• 已正确安装 NVIDIA 驱动，nvidia-smi 命令可以正常工作
• 已安装 NVIDIA Container Toolkit
• 普通 Docker 容器可以使用 GPU 资源（通过 docker run --gpus all 测试）

2. 配置容器运行时

对于 containerd 用户，确保 /etc/containerd/config.toml 包含正确的 NVIDIA 运行时配置：

version = 2
[plugins."io.containerd.grpc.v1.cri".containerd]
  default_runtime_name = "nvidia"
  
  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia]
    privileged_without_host_devices = false
    runtime_type = "io.containerd.runc.v2"
    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.nvidia.options]
      BinaryName = "/usr/bin/nvidia-container-runtime"

对于 Docker 用户，确保 /etc/docker/daemon.json 配置正确：

{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime"
    }
  }
}

3. 特殊环境处理

Minikube 用户：

Minikube 默认使用虚拟机，需要特别注意：

1. 使用 minikube addons enable nvidia-device-plugin
2. 使用 minikube addons enable nvidia-gpu-device-plugin
3. 确保虚拟机可以访问 GPU 资源

Docker Desktop 用户：

目前 Docker Desktop 的 Kubernetes 不支持 GPU 透传，建议使用其他 Kubernetes 发行版。

k3s 用户：

需要确保 k3s 的 containerd 配置正确加载 NVIDIA 运行时，并创建相应的 RuntimeClass。

4. 验证配置

创建测试 Pod 时，确保在容器规格中包含以下环境变量：

env:
- name: NVIDIA_VISIBLE_DEVICES
  value: all
- name: NVIDIA_DRIVER_CAPABILITIES
  value: all

同时正确设置资源限制：

resources:
  limits:
    nvidia.com/gpu: "1"

高级排查技巧

如果问题仍然存在，可以尝试以下方法：

1. 检查库文件路径：确认 libnvidia-ml.so.1 存在于标准库路径中
2. 检查挂载：确保容器内可以访问到宿主机的 /usr/lib/x86_64-linux-gnu/ 目录
3. 使用 NVIDIA GPU Operator：这是一个更全面的解决方案，可以自动处理大部分配置问题
4. 检查 kubelet 配置：确保 kubelet 使用正确的容器运行时

总结

NVIDIA k8s-device-plugin 的 libnvidia-ml.so.1 加载问题通常源于容器运行时配置不正确或环境隔离问题。通过正确配置容器运行时、验证基础环境、使用适当的 Kubernetes 插件或 Operator，大多数情况下可以解决这个问题。对于特殊环境如 Minikube 或 Docker Desktop，需要特别注意其特定的限制和配置要求。