K8s集群GPUDirect排错：从报错到验证的完整流程

GPUDirect 在 K8s 集群里出问题，通常不是单一原因导致的，而是 GPU 驱动、RDMA 网卡、容器运行时和网络插件多个环节叠加的结果。
如果你发现 Pod 里 nvidia-smi 正常但 GPU 与网卡之间的直接内存访问失败，或者应用报 NCCL 超时、ibv_reg_mr 错误，可以按下面的顺序逐步排查。
本文适合已经有一套可用的 K8s 集群、节点上装有 NVIDIA GPU 和 RDMA 网卡，但 GPUDirect 相关功能无法正常工作的场景。

先确认节点层面的 GPU 与 RDMA 是否就绪

节点本身没准备好，容器里怎么调都不会成功。
先登录到出问题的 GPU 节点，确认以下三个基础条件。

第一，NVIDIA 驱动和 CUDA 基础可用：

nvidia-smi
lsmod | grep nvidia

nvidia-smi 能列出 GPU 型号和驱动版本，lsmod 里能看到 nvidia、nvidia_uvm 等模块，说明驱动层正常。
如果这一步就报错，先解决驱动安装问题，不要继续往下查。

第二，RDMA 网卡和 nvidia-peermem 模块已加载。
GPUDirect RDMA 依赖 nvidia-peermem 把 GPU 显存注册给网卡，缺少它是最常见的“看不见”故障点：

lsmod | grep nvidia_peermem
ibv_devinfo

ibv_devinfo 应能看到至少一个状态为 PORT_ACTIVE 的 HCA 设备。
如果 nvidia_peermem 没加载，执行：

modprobe nvidia-peermem

然后再次用 lsmod 确认。
注意不同驱动版本对应不同模块名，部分版本叫 nvidia_peermem，如果报模块不存在，需要核对当前驱动包是否包含该组件。

第三，设备插件是否把 GPU 和 RDMA 资源正确上报：

kubectl get nodes -o json | grep -A5 capacity
kubectl describe node <节点名> | grep -E 'nvidia|rdma'

节点 Capacity 里应出现 nvidia.com/gpu 和对应的 RDMA 资源名（如 rdma/ib）。
如果 GPU 资源缺失，说明 NVIDIA device plugin 没正常运行；
如果 RDMA 资源缺失，检查 RDMA device plugin 或网络插件的配置。

排查容器内 GPUDirect 是否真正生效

节点层正常后，问题往往出在 Pod 的资源配置和权限上。
先进入一个带 GPU 的 Pod，检查容器内能否看到 GPU 和 RDMA 设备：

kubectl exec -it  -- nvidia-smi
kubectl exec -it  -- ls /dev/infiniband/

如果 /dev/infiniband/ 为空，说明 Pod 没有挂载 RDMA 设备。
检查 Pod 的 resources 里是否申请了 RDMA 资源：

resources:
  limits:
    nvidia.com/gpu: 1
    rdma/ib: 1

同时确认 Pod 没有以 privileged: false 运行却需要访问设备。
部分环境需要显式添加 securityContext 或使用支持 RDMA 的 CNI 插件。

再验证容器内 GPU 与网卡的互通性。
如果应用使用 NCCL，可以跑一个最小测试：

kubectl exec -it  -- nvidia-smi topo -m

输出中 GPU 与网卡之间如果显示 PIX 或 PHB 而非 SYS，说明拓扑连接正常；
如果显示 SYS，可能跨了 NUMA 节点，性能会下降但不一定报错。
真正判断 GPUDirect 是否启用，需要看应用日志里是否有 GPUDirect RDMA 启用标记，或使用 ibv_reg_mr 相关测试工具确认显存注册成功。

常见报错与对应修复方向

报错一：Failed to register MR 或 ibv_reg_mr failed

多数是 nvidia-peermem 未加载或版本不匹配。
先 modprobe nvidia-peermem，再确认驱动版本与网卡 OFED 驱动兼容。
如果仍然失败，检查容器是否限制了 memlock，在 Pod 的 securityContext 或容器运行时配置中放开内存锁定限制。

报错二：NCCL 超时或 no usable NIC found

先确认 Pod 内 ibv_devinfo 能看到活跃 HCA。
如果看不到，回到上一节检查 RDMA 资源申请和设备挂载。
如果能看到但 NCCL 仍不识别，检查 NCCL 环境变量，如 NCCL_IB_HCA 是否指定了正确的网卡名，NCCL_IB_DISABLE 是否为 0。

报错三：节点资源显示 GPU 正常但 Pod 调度失败

查看 kubectl describe pod 的 Events，常见原因是节点有污点未容忍，或 device plugin 的 Pod 处于 CrashLoopBackOff。
先 kubectl logs 查看 device plugin 日志，再检查节点标签和污点配置。

避坑与验证清单

修改任何模块或配置前，
先记录当前状态，
避免重启后无法回滚。modprobe 加载的模块在节点重启后会丢失，
需要写入 /etc/modules-load.d/ 或对应驱动配置中持久化。

不要只看 nvidia-smi 正常就认为 GPUDirect 可用，必须验证容器内 /dev/infiniband/ 设备存在且 ibv_devinfo 能看到活跃端口。

如果集群使用 Calico、Flannel 等普通 CNI，RDMA 设备可能不会自动注入 Pod，需要额外配置 RDMA CNI 或使用支持 SR-IOV 的网络方案。

最终验证建议在 Pod 内执行一次完整的 GPU 到网卡通信测试，确认应用日志中出现 GPUDirect 启用信息，并且没有 MR 注册失败或 NCCL 超时。
如果测试通过，再逐步把配置固化到节点启动项和 DaemonSet 中，避免下次重启后问题复现。