Merge pull request #2419 from spidernet-io/en/rdma

doc: add en rdma
spidernet-io · Oct 12, 2023 · b833ba5 · b833ba5
2 parents 1cde6cb + 60cf9d7
commit b833ba5
Show file tree

Hide file tree

Showing 2 changed files with 467 additions and 38 deletions.
diff --git a/docs/usage/rdma-zh_CN.md b/docs/usage/rdma-zh_CN.md
@@ -4,30 +4,30 @@
 
 ## 介绍
 
-Spiderpool 赋能了 macvlan ipvlan 和 SRIOV CNI， 这些 CNI 能让宿主机的 RDMA 网卡暴露给 POD 来使用，本章节将介绍在 Spiderpool 下如何 RDMA 网卡。
+Spiderpool 赋能了 macvlan、ipvlan 和 SR-IOV CNI， 这些 CNI 能让宿主机的 RDMA 网卡暴露给 Pod 来使用，本章节将介绍在 Spiderpool 下如何 RDMA 网卡。
 
 ## 功能
 
 RDMA 设备的网络命名空间具备 shared 和 exclusive 两种模式，容器因此可以实现共享 RDMA 网卡，或者独享 RDMA 网卡。在 kubernetes 下，可基于 macvlan 或 ipvlan CNI 来使用 shared 模式的
-RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
+RDMA 网卡，也可以基于 SR-IOV CNI 来使用 exclusive 模式的网卡。
 
-在 shared 模式下，Spiderpool 使用了 macvlan 或 ipvlan CNI 来暴露宿主机上的 RoCE 网卡给 PDO 使用，使用 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin) 来完成 RDMA 网卡资源的暴露和 POD 调度。
+在 shared 模式下，Spiderpool 使用了 macvlan 或 ipvlan CNI 来暴露宿主机上的 RoCE 网卡给 Pod 使用，使用 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin) 来完成 RDMA 网卡资源的暴露和 Pod 调度。
 
-在 exclusive 模式下，Spiderpool 使用了 [SRIOV CNI](https://github.com/k8snetworkplumbingwg/sriov-network-operator) 来暴露宿主机上的 RDMA 网卡给 PDO 使用，暴露 RDMA 资源。使用 [RDMA CNI](https://github.com/k8snetworkplumbingwg/rdma-cni) 来完成 RDMA 设备隔离。
+在 exclusive 模式下，Spiderpool 使用了 [SR-IOV CNI](https://github.com/k8snetworkplumbingwg/sriov-network-operator) 来暴露宿主机上的 RDMA 网卡给 Pod 使用，暴露 RDMA 资源。使用 [RDMA CNI](https://github.com/k8snetworkplumbingwg/rdma-cni) 来完成 RDMA 设备隔离。
 
 ### 基于 macvlan 或 ipvlan 共享使用具备 RoCE 功能的网卡
 
-以下步骤，在具备 2 个节点的集群上，演示如何基于 macvlan CNI 使得 POD 共享使用 RDMA 设备
+以下步骤演示在具备 2 个节点的集群上，如何基于 macvlan CNI 使得 Pod 共享使用 RDMA 设备：
 
 1. 在宿主机上，确保主机拥有 RDMA 网卡，且安装好驱动，确保 RDMA 功能工作正常。
 
-    本示例环境中，宿主机上具备 RoCE 功能的 mellanox ConnectX 5 网卡，可按照 [NVIDIA 官方指导](https://developer.nvidia.com/networking/ethernet-software) 安装最新的 OFED 驱动，。使用如下命令，可查询到 rdma 设备
+    本示例环境中，宿主机上具备 RoCE 功能的 mellanox ConnectX 5 网卡，可按照 [NVIDIA 官方指导](https://developer.nvidia.com/networking/ethernet-software) 安装最新的 OFED 驱动。使用如下命令，可查询到 RDMA 设备：
 
         ~# rdma link show
         link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev ens6f0np0
         link mlx5_1/1 state ACTIVE physical_state LINK_UP netdev ens6f1np1
 
-    确认主机上确认 rdma 子系统工作在 shared 模式下，否则，请切换到 模式，
+    确认主机上的 RDMA 子系统工作在 shared 模式下，否则，请切换到 shared 模式。
 
         ~# rdma system
         netns shared copy-on-fork on
@@ -37,12 +37,13 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
 
 2. 确认 RDMA 网卡的信息，用于后续 device plugin 发现设备资源。
 
-    本演示环境，输入如下，网卡 vendors 为 15b3，网卡 deviceIDs 为 1017
+    本演示环境，输入如下命令，网卡 vendors 为 15b3，网卡 deviceIDs 为 1017
+
         ~# lspci -nn | grep Ethernet
         af:00.0 Ethernet controller [0200]: Mellanox Technologies MT27800 Family [ConnectX-5] [15b3:1017]
         af:00.1 Ethernet controller [0200]: Mellanox Technologies MT27800 Family [ConnectX-5] [15b3:1017]
 
-3. 可参考 [安装](./install/underlay/get-started-macvlan-zh_CN.md) 安装 Spiderpool 并配置 sriov-network-operator。其中，按照命令务必加上如下 helm 选项来安装 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin)
+3. 可参考 [安装](./install/underlay/get-started-macvlan-zh_CN.md) 安装 Spiderpool 并配置 sriov-network-operator。其中，安装命令务必加上如下 helm 选项以安装 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin)：
 
         helm install spiderpool spiderpool/spiderpool -n kube-system \
            --set multus.multusCNI.defaultCniCRName="macvlan-conf" \
@@ -55,7 +56,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
        
     > 如果您是国内用户，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` 避免 Spiderpool 的镜像拉取失败。
     >
-    > 注：完成 spiderpool 安装后，可以手动编辑 configmap spiderpool-rdma-shared-device-plugin 来重新配置 RDMA shared device plugin
+    > 完成 Spiderpool 安装后，可以手动编辑 configmap spiderpool-rdma-shared-device-plugin 来重新配置 RDMA shared device plugin。
 
     完成后，安装的组件如下
 
@@ -69,7 +70,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
         spiderpool-rdma-shared-device-plugin-dr7w8     1/1     Running     0          1m
         spiderpool-rdma-shared-device-plugin-zj65g     1/1     Running     0          1m
 
-4. 查看 node 的可用资源，其中包含了上报的 rdma 设备资源
+4. 查看 node 的可用资源，其中包含了上报的 RDMA 设备资源：
 
         ~# kubectl get no -o json | jq -r '[.items[] | {name:.metadata.name, allocable:.status.allocatable}]'
           [
@@ -121,7 +122,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
               ipv4: ["v4-81"]
         EOF
 
-6. 使用上一步骤的配置，来创建一组跨节点的 DaemonSet 应用
+6. 使用上一步骤的配置，来创建一组跨节点的 DaemonSet 应用：
 
         ANNOTATION_MULTUS="v1.multus-cni.io/default-network: kube-system/macvlan-ens6f0np0"
         RESOURCE="spidernet.io/hca_shared_devices"
@@ -163,9 +164,9 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
                   sleep 1000000
         EOF
 
-7. 在跨加点的 POD 之间，确认 RDMA 收发数据正常
+7. 在跨节点的 Pod 之间，确认 RDMA 收发数据正常。
 
-    开启一个终端，进入一个 POD 启动服务
+    开启一个终端，进入一个 Pod 启动服务：
 
         # 能看到宿主机上的所有 RDMA 网卡
         ~# rdma link
@@ -175,14 +176,14 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
         # 启动一个 RDMA 服务
         ~# ib_read_lat
 
-   开启一个终端，进入另一个 POD 访问服务
+    开启一个终端，进入另一个 Pod 访问服务：
 
         # 能看到宿主机上的所有 RDMA 网卡
         ~# rdma link
         0/1: mlx5_0/1: state ACTIVE physical_state LINK_UP
         1/1: mlx5_1/1: state ACTIVE physical_state LINK_UP
         
-        # 访问对方 POD 的服务
+        # 访问对方 Pod 的服务
         ~# ib_read_lat 172.81.0.120
         ---------------------------------------------------------------------------------------
                             RDMA_Read Latency Test
@@ -208,42 +209,42 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
          2       1000          6.88           16.81        7.04              7.06         0.31      7.38        16.81
         ---------------------------------------------------------------------------------------
 
-### 基于 SRIOV 隔离使用 RDMA 网卡
+### 基于 SR-IOV 隔离使用 RDMA 网卡
 
-以下步骤，在具备 2 个节点的集群上，演示如何基于 SRIOV CNI 使得 POD 隔离使用 RDMA 设备
+以下步骤演示在具备 2 个节点的集群上，如何基于 SR-IOV CNI 使得 Pod 隔离使用 RDMA 设备：
 
-1. 在宿主机上，确保主机拥有 RDMA 和 SRIOV 功能的网卡，且安装好驱动，确保 RDMA 功能工作正常。
+1. 在宿主机上，确保主机拥有 RDMA 和 SR-IOV 功能的网卡，且安装好驱动，确保 RDMA 功能工作正常。
 
-    本示例环境中，宿主机上具备 RoCE 功能的 mellanox ConnectX 5 网卡，可按照 [NVIDIA 官方指导](https://developer.nvidia.com/networking/ethernet-software) 安装最新的 OFED 驱动，。
+    本示例环境中，宿主机上具备 RoCE 功能的 mellanox ConnectX 5 网卡，可按照 [NVIDIA 官方指导](https://developer.nvidia.com/networking/ethernet-software) 安装最新的 OFED 驱动。
 
-    > 注意：要隔离使用 RDMA 网卡，务必满足如下其中一个条件
+    > 要隔离使用 RDMA 网卡，务必满足如下其中一个条件：
     > 
-    > (1) Kernel based on 5.3.0 or newer, RDMA modules loaded in the system. rdma-core package provides means to automatically load relevant modules on system start
+    > (1) 内核版本要求 5.3.0 或更高版本，并在系统中加载 RDMA 模块。rdma-core 软件包提供了在系统启动时自动加载相关模块的功能。
     > 
-    > (2) Mellanox OFED version 4.7 or newer is required. In this case it is not required to use a Kernel based on 5.3.0 or newer.
+    > (2) Mellanox OFED 要求 4.7 或更高版本。此时不需要使用 5.3.0 或更新版本的内核。
     
-    使用如下命令，可查询到 rdma 设备
+    使用如下命令，可查询到 RDMA 设备：
 
         ~# rdma link show
         link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev ens6f0np0
         link mlx5_1/1 state ACTIVE physical_state LINK_UP netdev ens6f1np1
 
-    确认主机上确认 rdma 子系统工作在 shared 模式下，否则，请切换到 模式，
+    确认主机上的 RDMA 子系统工作在 exclusive 模式下，否则，请切换到 exclusive 模式。
 
-        # 切换到 exclusive 模式，重启重启失效 
+        # 切换到 exclusive 模式，重启主机失效 
         ~# rdma system set netns exclusive
         # 持久化配置
         ~# echo "options ib_core netns_mode=0" >> /etc/modprobe.d/ib_core.conf
 
         ~# rdma system
         netns exclusive copy-on-fork on
 
-    确认网卡具备 SRIOV 功能，查看支持的最大 VF 数量
+    确认网卡具备 SR-IOV 功能，查看支持的最大 VF 数量：
 
         ~# cat /sys/class/net/ens6f0np0/device/sriov_totalvfs
         127
 
-    （可选）SRIOV 场景下，应用可使 NVIDIA 的 GPUDirect RMDA 功能，可参考 [官方文档](https://network.nvidia.com/products/GPUDirect-RDMA/) 安装内核模块。
+    （可选）SR-IOV 场景下，应用可使 NVIDIA 的 GPUDirect RMDA 功能，可参考 [官方文档](https://network.nvidia.com/products/GPUDirect-RDMA/) 安装内核模块。
 
 2. 确认 RDMA 网卡的信息，用于后续 device plugin 发现设备资源。
 
@@ -261,7 +262,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
 
     > 如果您是国内用户，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` 避免 Spiderpool 的镜像拉取失败。
     >
-    > 注：完成 spiderpool 安装后，可以手动编辑 configmap spiderpool-rdma-shared-device-plugin 来重新配置 RDMA shared device plugin
+    > 完成 Spiderpool 安装后，可以手动编辑 configmap spiderpool-rdma-shared-device-plugin 来重新配置 RDMA shared device plugin
 
     完成后，安装的组件如下
 
@@ -273,9 +274,9 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
         spiderpool-multus-ckjrl                        1/1     Running     0          1m
         spiderpool-multus-mjl7z                        1/1     Running     0          1m
 
-4. 配置 SRIOV operator
+4. 配置 SR-IOV operator
 
-    如下配置，使得 SRIOV operator 能够在宿主机上创建出 VF，并上报资源
+    如下配置，使得 SR-IOV operator 能够在宿主机上创建出 VF，并上报资源
 
         cat <<EOF | kubectl apply -f -
         apiVersion: sriovnetwork.openshift.io/v1
@@ -298,7 +299,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
           isRdma: true
         EOF
 
-    查看 node 的可用资源，其中包含了上报的 SRIOV 设备资源
+    查看 node 的可用资源，其中包含了上报的 SR-IOV 设备资源
 
         ~# kubectl get no -o json | jq -r '[.items[] | {name:.metadata.name, allocable:.status.allocatable}]'
         [
@@ -314,7 +315,7 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
           ...
         ]
 
-5. 创建 SRIOV 相关的 multus 配置，并创建配套的 ippool 资源
+5. 创建 SR-IOV 相关的 multus 配置，并创建配套的 ippool 资源
 
         cat <<EOF | kubectl apply -f -
         apiVersion: spiderpool.spidernet.io/v2beta1
@@ -383,24 +384,24 @@ RDMA 网卡，也可以基于 SRIOV CNI 来使用 exclusive 模式的网卡。
                   sleep 1000000
         EOF
 
-7. 在跨加点的 POD 之间，确认 RDMA 收发数据正常
+7. 在跨节点的 Pod 之间，确认 RDMA 收发数据正常
 
-   开启一个终端，进入一个 POD 启动服务
+    开启一个终端，进入一个 Pod 启动服务：
 
-        # 只能看到分配给 POD 的一个 RDMA 设备
+        # 只能看到分配给 Pod 的一个 RDMA 设备
         ~# rdma link
         7/1: mlx5_3/1: state ACTIVE physical_state LINK_UP netdev eth0
         
         # 启动一个 RDMA 服务
         ~# ib_read_lat
 
-   开启一个终端，进入另一个 POD 访问服务
+    开启一个终端，进入另一个 Pod 访问服务：
 
         # 能看到宿主机上的所有 RDMA 网卡
         ~# rdma link
         10/1: mlx5_5/1: state ACTIVE physical_state LINK_UP netdev eth0
         
-        # 访问对方 POD 的服务
+        # 访问对方 Pod 的服务
         ~# ib_read_lat 172.81.0.118
         libibverbs: Warning: couldn't stat '/sys/class/infiniband/mlx5_4'.
         libibverbs: Warning: couldn't stat '/sys/class/infiniband/mlx5_2'.