nvml-mock #

📝 摘要 #

nvml-mock 是 NVIDIA 官方的 Kubernetes Helm Chart，通过 CGo 编译的 mock libnvidia-ml.so 共享库，在无物理 GPU 的集群中模拟完整的多 GPU 环境，使 nvidia-smi、device plugin、DRA driver 等 GPU 相关 K8s 组件无需真实硬件即可运行和测试。它部署为 DaemonSet + ConfigMap + RBAC，在每个节点上创建 mock NVML 库、设备节点、InfiniBand sysfs 树和 PCI sysfs 树，消费者通过 --nvidia-driver-root=/var/lib/nvml-mock/driver 接入。内置 7 个 GPU profile（A100/GB300 覆盖 Ampere→Blackwell Ultra），支持 InfiniBand 三层 LD_PRELOAD 模拟（sysfs+UMAD+verbs）、PCIe 拓扑模拟、NRI 插件透明注入、动态指标和故障注入（lost/fallen_off_bus/ecc_uncorrectable）。主要限制是 Go 程序的 PCIe sysfs 拦截问题导致 DRA 拓扑感知调度不可用。

核心概念： 用 CGo mock NVML 共享库替代真实 GPU 驱动，使任何通过标准 NVML API 查询的程序都能在无 GPU 环境中正常工作，实现 GPU 依赖组件的零硬件测试。

关键技术栈 / 关键要点：

1. CGo mock NVML 库 — 编译为 libnvidia-ml.so，实现完整 NVML API，nvidia-smi 可直接运行
2. 7 个内置 GPU Profile — A100→GB300 覆盖 Ampere/Hopper/Blackwell/Blackwell Ultra，含真实规格（显存/NVLink/TDP/驱动版本）
3. InfiniBand 三层 LD_PRELOAD — libibmocksys.so+libibmockumad.so+libibmockverbs.so 协同模拟 IB，ibstat/ibping/iblinkinfo 可用
4. NRI 插件透明注入 — 容器创建时注入 mock 环境，普通 pod 无需修改 pod-spec 即可运行 nvidia-smi
5. 故障注入 — 4 种模式（healthy/lost/fallen_off_bus/ecc_uncorrectable），支持确定性和随机性触发
6. 与 fake-gpu-operator 互补 — 驱动级保真（NVML API）vs K8s API 级规模模拟（虚拟节点）

关键结论 / 实践建议： 使用 a100 profile 兼容性最广；安装 NRI 插件时必须指定独立 namespace（-n nvml-mock --create-namespace）；Go 程序的 LD_PRELOAD 限制是当前最大已知问题，DRA 拓扑感知调度暂时不可用。

一句话定义：nvml-mock 是 NVIDIA 官方的 Kubernetes Helm Chart，通过 CGo 实现的 mock NVML 共享库，在无物理 GPU 的集群中模拟完整的多 GPU 环境，用于测试 GPU 相关的 K8s 组件。

Open: Pasted image 20260804132544.png

概览 #

核心架构 #

设计思路 #

nvml-mock 的核心是 CGo 编译的 libnvidia-ml.so 共享库，它实现了完整的 NVML API，但返回的是配置文件中定义的静态/动态数据。任何通过标准 NVML API 查询 GPU 的程序（nvidia-smi、device plugin、DRA driver）都能正常工作，无需知道底层是模拟的。

部署组件 #

Chart 部署三个核心资源：

┌─────────────────────────────────────────────────────┐
│                    Helm Release                      │
├─────────────┬───────────────┬───────────────────────┤
│  DaemonSet  │   ConfigMap   │        RBAC           │
│  (每个节点)  │  (GPU 配置)    │  (Node label 权限)    │
└──────┬──────┴───────┬───────┴───────────────────────┘
       │              │
       ▼              ▼
 ┌─────────────────────────────────────────────────┐
 │          /var/lib/nvml-mock/                     │
 │  ├── driver/usr/lib64/libnvidia-ml.so.*         │
 │  ├── driver/dev/nvidia{N,ctl,-uvm,-uvm-tools}   │
 │  ├── driver/config/config.yaml                  │
 │  ├── ib/sys/class/infiniband/...                │
 │  └── sys/bus/pci/devices/...                    │
 └─────────────────────────────────────────────────┘

1. DaemonSet — 特权容器（privileged: true，需要 mknod），在每个节点上：

   • 复制 libnvidia-ml.so.{version} 到 /var/lib/nvml-mock/driver/usr/lib64/
   • 创建符号链接处理库版本化
   • 创建 mock 设备节点 /dev/nvidia{N,ctl,-uvm,-uvm-tools}
   • 写入 GPU 配置 YAML
   • 给节点打标签 nvidia.com/gpu.present=true
   • 写入 NFD feature file 生成 feature.node.kubernetes.io/pci-10de.present=true
   • 创建 fake InfiniBand sysfs 树
   • 创建 fake PCI sysfs 树

2. ConfigMap — 从选定的 GPU profile 生成的 GPU 配置

3. RBAC — ServiceAccount，拥有节点标签修补权限

消费者接入 #

消费者组件挂载 /var/lib/nvml-mock 并使用 --nvidia-driver-root=/var/lib/nvml-mock/driver，通过标准 NVML API 路径发现 GPU：

# Device Plugin 示例
kubectl apply -f tests/e2e/device-plugin-mock.yaml

# DRA Driver 示例
helm install nvidia-dra-driver-gpu nvidia/nvidia-dra-driver-gpu \
  --set nvidiaDriverRoot=/var/lib/nvml-mock/driver

Dockerfile 构建产物 #

构建阶段（golang:1.26.5-bookworm） #

Mock 共享库（CGo 编译）：

Go 二进制：

运行阶段（debian:bookworm-slim） #

• 安装 InfiniBand 工具（infiniband-diags, rdma-core, ibverbs-utils）
• 提取 nvidia-smi（从 NVIDIA 580 分支，支持 GB200 NVLink5）
• 下载 kubectl v1.36.1
• 用 patchelf 设置 RPATH（$ORIGIN/../lib64）使工具在重定位挂载上下文中找到库

GPU Profiles #

七个内置 profile 提供真实的数据中心 GPU 规格：

选择建议：

• a100 — 兼容性最广，多数 NVIDIA 软件假定 A100
• h100 — Hopper 特性：FP8、Transformer Engine、PCIe Gen5
• b200 — Blackwell 特性：FP4、NVLink v5、PCIe Gen6
• gb200/gb300 — Grace-Blackwell Superchip：NVLink-C2C、统一内存
• l40s — Ada Lovelace 推理：FP8、PCIe Gen4
• t4 — 低功耗推理（70W）

InfiniBand 模拟 #

三层 LD_PRELOAD 架构 #

三个 shim 协同工作（预加载顺序 libibmockumad.so:libibmockverbs.so:libibmocksys.so）：

┌──────────────────────────────────────────────────────────┐
│                    用户态进程                              │
│  (ibstat, ibstatus, iblinkinfo, ibv_devinfo -l)          │
├──────────────────────────────────────────────────────────┤
│  libibmocksys.so   → 重写 /sys/class/infiniband* 路径    │
│  libibmockumad.so  → 代理 libibumad 到 mock-ib daemon    │
│  libibmockverbs.so → 代理 /dev/infiniband/uverbsN        │
├──────────────────────────────────────────────────────────┤
│  mock-ib daemon (Unix socket)                            │
│  → SA 路径查询 / ibping / SMP 合成                        │
├──────────────────────────────────────────────────────────┤
│  fake sysfs 树 (/var/lib/nvml-mock/ib/sys/class/...)     │
└──────────────────────────────────────────────────────────┘

• libibmocksys.so — 重写 sysfs 访问，使 ibstat/ibstatus/iblinkinfo 读取 mock 树
• libibmockumad.so — 代理 libibumad 的 umad_send/umad_recv 到 mock-ib daemon
• libibmockverbs.so — 代理 /dev/infiniband/uverbsN，使 libibverbs 枚举 HCA

Profile 默认 IB 配置 #

跨节点 ibping #

mock-ib 在每个 pod 中启动，暴露 headless Service（端口 18515）用于 TCP fabric relay。Chart 自带 NetworkPolicy 限制入站流量仅来自 nvml-mock pods。

验证脚本：tests/e2e/validate-ibping.sh

IB 配置 schema #

PCIe 拓扑模拟 #

每个 profile 包含 pcie_topology: 块，描述主机的 PCI root complex 布局。render-pci-sysfs 启动时读取并写入 fake sysfs 树。

Profile 默认拓扑 #

验证规则 #

render-pci-sysfs 启动时验证：

• 每个 BDF 必须也出现在 devices[] 中
• 每个 BDF 最多属于一个 root complex
• Root complex ID 必须匹配 pciDDDD:BB
• BDF 必须使用 4 位域格式（DDDD:BB:DD.F）

NRI 插件（可选） #

当 nri.enabled=true 时，Chart 额外部署 nvml-mock-nri — 一个 node-local containerd NRI 插件，在容器创建时注入 mock 环境，使普通 pod 能运行 nvidia-smi 而无需 pod-spec 修改。

工作原理 #

Container 创建请求
    │
    ▼
┌─────────────────────────────────┐
│  nvml-mock-nri (NRI Plugin)     │
│  1. 挂载 host overlay 到容器     │
│  2. 注入 mock 环境变量/设备      │
│  3. 写入 OCI spec 调整          │
└─────────────────────────────────┘
    │
    ▼
容器启动 → nvidia-smi 可用

设备注入模式 #

⚠️ 重要：安装时必须指定独立 namespace（-n nvml-mock --create-namespace），否则 NRI 插件会排除 default namespace，所有 pod 都不会被注入。

故障模式 #

Chart 的姿态是 "可检测的 fail-open"：

动态指标 #

默认 mock 完全静态。设置 gpu.dynamicMetrics.enabled=true 使 mock 返回波动值：

温度 #

功耗 #

利用率 #

解析优先级：chart baseline < profile default < user override

故障注入 #

设置 gpu.failureInjection.enabled=true 模拟 GPU 故障：

触发方式：

• 确定性：after_calls: N（第 N 次 NVML 调用后激活）
• 随机性：probability: 0.0~1.0（每次调用概率触发）

故障注入可与动态指标组合：设备在健康时返回动态读数，触发后切换到故障模式。一旦触发，设备在 pod 生命周期内保持故障状态。

Helm Values 配置 #

核心 GPU 设置 #

镜像 & 调度 #

InfiniBand #

NRI 插件 #

fake-gpu-operator 集成 #

快速开始 #

Device Plugin on KIND #

# 1. 创建集群
kind create cluster --name nvml-mock-test

# 2. 加载镜像
docker pull ghcr.io/nvidia/nvml-mock:latest
kind load docker-image ghcr.io/nvidia/nvml-mock:latest --name nvml-mock-test

# 3. 安装 nvml-mock
helm install nvml-mock oci://ghcr.io/nvidia/k8s-test-infra/chart/nvml-mock \
  --wait --timeout 120s

# 4. 验证
kubectl rollout status daemonset/nvml-mock --timeout=60s

# 5. 部署 device plugin
kubectl apply -f tests/e2e/device-plugin-mock.yaml

# 6. 检查可分配 GPU
kubectl get nodes -o jsonpath='{.items[0].status.allocatable.nvidia\.com/gpu}'
# 期望: 8

DRA Driver on KIND #

# 1. 创建启用 DRA 的集群
kind create cluster --name nvml-mock-dra \
  --config tests/e2e/kind-dra-config.yaml

# 2. 安装 nvml-mock（同上）

# 3. 安装 DRA driver
helm repo add nvidia https://helm.ngc.nvidia.com/nvidia
helm install nvidia-dra-driver-gpu nvidia/nvidia-dra-driver-gpu \
  --set nvidiaDriverRoot=/var/lib/nvml-mock/driver \
  --set gpuResourcesEnabledOverride=true \
  --set resources.computeDomains.enabled=false

# 4. 验证 ResourceSlices
kubectl get resourceslices -o jsonpath='{.items[0].spec.devices}' | jq length
# 期望: 8

多节点异构 GPU 集群 #

# 1. 创建带标签 worker 的 Kind 集群
kind create cluster --name gpu-fleet \
  --config tests/e2e/kind-multi-node-config.yaml

# 2. 安装不同 profile
# A100 节点
helm install nvml-mock-a100 oci://ghcr.io/nvidia/k8s-test-infra/chart/nvml-mock \
  --set gpu.profile=a100 --set gpu.count=4 \
  --set nodeSelector.nvml-mock/profile=a100

# T4 节点
helm install nvml-mock-t4 oci://ghcr.io/nvidia/k8s-test-infra/chart/nvml-mock \
  --set gpu.profile=t4 --set gpu.count=2 \
  --set nodeSelector.nvml-mock/profile=t4

与 fake-gpu-operator 的关系 #

启用集成后，nvml-mock 为每个 profile 创建 gpu-profile-<name> ConfigMap，FGO 的 loader 读取。需设置 FGO 的 builtinProfiles.enabled=false。

节点标签 #

NFD 的 PCI source 无法看到 mock GPU，因为 nfd-worker 是静态链接的，LD_PRELOAD 对其无效。Feature file 是 workaround。

已知限制 #

前置条件 #

集群要求：允许特权 pod；DRA 需要 K8s 1.32+ 且启用 DynamicResourceAllocation feature gate。

相关链接 #

• GitHub 仓库
• Helm Chart README
• go-nvml mock 包
• E2E 测试工作流
• PCIe sysfs 限制 Issue #265

调研日期：2026-08-02