GitHub 源码知乎专栏

RDMA 高速网络部署

给 k8s 节点装 RDMA/IB/RoCE 网卡驱动、在 CubeStudio 里给训练 Pod 分配 RDMA 设备、排查 InfiniBand/Mellanox 网卡问题时读这篇

02-部署安装 / 网络
RDMArdmaInfiniBandIBRoCERoCE over Converged EthernetMellanoxmellanoxMLNX_OFEDofedmlxconfigib_read_bwk8s-rdma-shared-dev-pluginrdma/hcadevice pluginNCCL

RDMA 高速网络部署（InfiniBand / RoCE / Mellanox）

RDMA（Remote Direct Memory Access）提供低延迟、高带宽、低 CPU 占用的网络传输，是多机多卡分布式训练（NCCL 通信）和高性能存储的关键。CubeStudio 通过 k8s-rdma-shared-dev-plugin 把宿主机的 RDMA 网卡以 rdma/hca 资源的形式暴露给 Pod。

本文合并自三份源码侧文档：

  • install/kubernetes/rdma/readme.md（驱动安装与验证总述）
  • install/kubernetes/rdma/roce.md（在 k8s 中使用 Mellanox RoCE 模式）
  • install/kubernetes/rdma/mellanox/readme.md（Mellanox 命令速查）

并补充了 install/kubernetes/rdma/ 下的实际部署 YAML（device plugin DaemonSet、测试 Pod 等）。

两种链路层：ibv_devinfo 输出 Link layer: InfiniBand 表示走 IB 网络；link_layer: Ethernet 表示走 RoCE（以太网承载 RDMA）。

一、节点驱动安装与验证（总述）

先重启机器，避免以前的安装需要重启才生效。

1. 查看系统内核

# centos
yum update -y
# ubuntu
apt update -y

rpm -qa | grep kernel   # 查看最新的 kernel 包版本
uname -r                # 查看操作系统当前运行的内核版本

对比上面两者是否一致，不一致需要重启。

2. 安装依赖包

# centos
yum install -y gcc-c++ dkms cmake kernel-devel kernel-headers libnl3 libnl3-devel
# ubuntu
apt-get install -y dkms cmake libnl-3-dev libnl-route-3-dev kernel-headers
apt-get install -y python-libxml2 gfortran libgfortran3 libnl-route-3-200 dpatch quilt bison \
  swig debhelper automake libltdl-dev chrpath flex autoconf m4 autotools-dev graphviz lsb-core

3. 安装/加载驱动

/etc/init.d/openibd restart   # 重新加载 RDMA 驱动
ibstat                        # 查看 IB 状态
ibstatus                      # 查询状态是否激活

4. 安装软件测试包并检查 RDMA 库

apt update && apt install -y infiniband-diags

检查是否已安装 RDMA 相关库：

dpkg -l perftest ibverbs-providers libibumad3 libibverbs1 libnl-3-200 libnl-route-3-200 librdmacm1

如有软件包未安装，执行：

apt update && apt install -y perftest ibverbs-providers libibumad3 libibverbs1 \
  libnl-3-200 libnl-route-3-200 librdmacm1

然后再次用 dpkg -l ... 确认安装结果。

5. 检查设备

  • lspci：检查本地是否有 IB 卡。
  • ibstatus：查询状态是否激活。
  • ibv_devices：查看本主机的 InfiniBand 设备。
  • ibnodes：查看网络中的 InfiniBand 设备（RoCE 网络不一定有 IB 设备）。
  • ibv_devinfo：查询设备信息。Link layer: InfiniBand 表示 IB 网络，link_layer: Ethernet 表示 RoCE。

二、RoCE 模式（Mellanox over Ethernet）

在 Kubernetes 中使用 Mellanox 网卡的 RoCE（RDMA over Converged Ethernet）模式，需要结合硬件配置、驱动设置、Kubernetes 网络插件以及 RDMA 容器化支持。

1. 确认硬件和驱动支持

  • 网卡型号：确保 Mellanox 网卡支持 RoCE（如 ConnectX-4/5/6 系列）。

  • 驱动和固件：安装最新 MLNX_OFED 驱动（Linux）或 WinOF-2（Windows）。用 mlxconfig 把网卡切换为 RoCE（ETH 模式）：

    mlxconfig -d <device> set LINK_TYPE_P1=2  # 2 = ETH 模式（RoCE）
reboot                                    # 需重启生效

  • 验证模式：ibv_devinfo 查看网卡是否显示为 RoCE 设备。

2. 配置 RoCE 网络环境

  • 交换机设置：启用 PFC（Priority Flow Control）和 ECN（Explicit Congestion Notification）以避免拥塞；若使用链路聚合（LAG），需配置 LACP（模式 4）并匹配服务器的 Bond 配置。

  • 服务器端优化：设置 MTU（通常为 4200）并开启 PFC：

    ifconfig <interface> mtu 4200
mlnx_qos -i <interface> --pfc=0,0,0,0,1,0,0,0 --trust=dscp

    关闭流控卸载（如 Flow Control）以减少 CPU 开销。

3. Kubernetes 节点配置

加载 RDMA 内核模块：

modprobe rdma_rxe   # 可选：Soft-RoCE 支持
modprobe ib_uverbs

安装 RDMA device plugin，使 Kubernetes 能识别 RDMA 设备（社区参考方案）：

kubectl apply -f https://raw.githubusercontent.com/Mellanox/k8s-rdma-shared-dev-plugin/master/deployment/k8s-rdma-shared-dev-plugin-daemonset.yaml

CubeStudio 自带了改造后的 device plugin DaemonSet，见下文「四、CubeStudio 实际部署」，生产部署请用仓库内的 install/kubernetes/rdma/mellanox/daemonset.yaml，而非上面这条社区示例命令。

验证设备是否可见：

kubectl describe node <node-name> | grep rdma

4. 容器化应用配置

在 Pod 的 resources.limits 中请求 RDMA 资源：

resources:
  limits:
    rdma/rdma_shared_device: "1"  # 请求 1 个 RDMA 设备

注意：这里的 rdma/rdma_shared_device 是通用示例，实际资源名取决于 device plugin ConfigMap 中的 resourceName。CubeStudio 仓库内 device plugin 的配置为 resourceName: "hca"（见 install/kubernetes/rdma/mellanox/daemonset.yaml 的 ConfigMap），对应 Pod 应请求 rdma/hca（与 install/kubernetes/rdma/mellanox/test-hca-pod.yaml 一致）。请以实际部署的 device plugin 配置中的 resourceName 为准。

也可直接把 RDMA 设备挂载到容器：

volumeMounts:
- name: rdma-devices
  mountPath: /dev/infiniband
volumes:
- name: rdma-devices
  hostPath:
    path: /dev/infiniband

应用兼容性：确保容器内应用支持 RDMA Verbs API（如使用 libibverbs 库）；测试工具 ib_write_bw / ib_read_bw 可用于验证带宽。

5. 网络插件选择

  • Multus：支持多网络接口，可为 Pod 附加 RoCE 网络（需配置 RDMA CNI）。
  • Kube-OVN/Calico：需确保不干扰 RDMA 流量（避免封装 overhead）。
  • 避免使用 Service Mesh（如 Istio）或网络策略插件，可能干扰 RDMA 性能。

6. 性能调优

NCCL 参数（AI 训练场景）：

env:
- name: NCCL_IB_TC
  value: "128"   # 匹配 PFC 队列
- name: NCCL_IB_QPS_PER_CONNECTION
  value: "8"     # 增加 QP 数量

NUMA 亲和性：绑定 Pod 到与网卡相同的 NUMA 节点以减少延迟。

常见问题

  • 驱动加载失败：检查内核版本兼容性，更新 MLNX_OFED 驱动。
  • RoCE 性能差：确认交换机 PFC 配置，并禁用 TCP 卸载（如 ethtool -K <interface> tso off gso off）。

三、Mellanox 命令速查

设备/驱动信息

ofed_info                  # 查看 OFED 驱动信息（IB 驱动版本）
ibstat                     # 查询 InfiniBand 设备的基本状态
ibstatus                   # 网卡信息
ibv_devinfo                # 网卡设备信息（ibv_devinfo -d mlx5_0 -v）
ibv_devices                # 查看本主机的 infiniband 设备
ibnodes                    # 查看网络中的 infiniband 设备
show_gids                  # 查看网卡支持的 roce 版本
show_counters              # 网卡端口统计数据（发送/接收数据大小）
mlxconfig -d mlx5_1 q      # 查询网卡配置信息

网络设备映射与链路验证

ibdev2netdev               # 查看 ib 设备与网络设备(ibX/ethX)的映射
ibdev2netdev -v            # 详细模式
hca_self_test.ofed         # 验证 InfiniBand 链接是否已启动（Mellanox）

配置与信息文件

/etc/infiniband/info           # Mellanox OFED 安装信息
/etc/infiniband/openib.conf    # 自动加载的模块列表
lspci | grep Mellanox          # 检查 Mellanox 网卡是否安装及型号
modinfo mlx5_core              # 查看驱动版本
ip a                           # 查看系统所有网卡及工作状态

重启 RDMA 驱动

/etc/init.d/openibd restart    # 重启 RDMA 驱动
service ibacm start            # 启动 ibacm（名称/地址解析服务）

注意：service network restart 只能启动 Ethernet 端口，并不会真正加载 RDMA 驱动。若驱动异常，/etc/init.d/openibd restart 会暴露很多错误，记得同时启动 ibacm。

信息收集脚本：/usr/sbin/sysinfo-snapshot.py。

参考资料：

四、CubeStudio 实际部署（install/kubernetes/rdma/）

1. 节点打标

device plugin DaemonSet 通过 nodeSelector: rdma: 'true' 调度，只在打了标签的节点上运行。先给有 RDMA 网卡的节点打标：

kubectl label node <node-name> rdma=true

2. 部署 RDMA Device Plugin（Mellanox 共享设备）

install/kubernetes/rdma/mellanox/daemonset.yaml 包含一个 ConfigMap 和一个 DaemonSet：

  • ConfigMap rdma-devices（命名空间 kube-system）声明资源 resourceName: "hca"，按厂商 vendors: ["15b3"]（Mellanox）匹配网卡，rdmaHcaMax: 500，periodicUpdateInterval: 300。
  • DaemonSet rdma-shared-dp-ds（命名空间 kube-system）使用镜像 ccr.ccs.tencentyun.com/cube-studio/k8s-rdma-shared-dev-plugin:mellanox，hostNetwork: true、privileged: true、nodeSelector: rdma: 'true'。
kubectl apply -f install/kubernetes/rdma/mellanox/daemonset.yaml

部署后，节点会上报 rdma/hca 可分配资源（用 kubectl describe node <node> | grep rdma 验证）。

如需 CDI（Container Device Interface）支持，使用 install/kubernetes/rdma/mellanox/cdi.yaml，它额外挂载了 /var/run/cdi，并演示了按 devices: ["ib0","ib1"] 或 selectors（vendor 15b3 / deviceID 1017 / ifNames）声明多个资源（hca_shared_devices_a / hca_shared_devices_b）。

3. 测试 Pod

install/kubernetes/rdma/mellanox/test-hca-pod.yaml 起一个 Deployment rdma-test，请求 rdma/hca: '1'，并加 IPC_LOCK capability，用 ib_read_bw -d mlx5_0 验证带宽：

kubectl apply -f install/kubernetes/rdma/mellanox/test-hca-pod.yaml
# 进入容器后：
ls -l /dev/infiniband /sys/class/infiniband /sys/class/net
ib_read_bw -d mlx5_0                       # 服务端
ib_read_bw -d mlx5_0 <container_ip>        # 客户端

4. 阿里云 eRDMA 变体（可选）

install/kubernetes/rdma/ali/ 提供阿里云环境的变体：

  • erdma.yaml：device plugin DaemonSet rdma-device-plugin（镜像 registry.cn-shanghai.aliyuncs.com/acs/rdma-device-plugin，ConfigMap 用 {"mode":"hca"}，nodeSelector: rdma: "true"，容忍 CriticalAddonsOnly）。
  • demo.yaml：两个测试 Pod（rdma-test-pod / rdma-test-pod-1），镜像 mellanox/centos_7_4_mofed_4_2_1_2_0_0_60，请求 rdma/hca: 1，用 ib_read_bw -q 30 测试。

本页命令、镜像名、资源名以源码为准（install/kubernetes/rdma/ 下 readme.md / roce.md / mellanox/* / ali/*），仅供导航与说明。

最后更新 2026-07-04完整文档以官方仓库为准：GitHub Wiki