Merge pull request #4106 from windsonsea/aiform

[docs] Fix indentations in ai/get-started-macvlan
spidernet-io · Sep 26, 2024 · bc05323 · bc05323
2 parents 55dbd73 + 5c9cbeb
commit bc05323
Show file tree

Hide file tree

Showing 2 changed files with 82 additions and 81 deletions.
diff --git a/docs/usage/install/ai/get-started-macvlan-zh_CN.md b/docs/usage/install/ai/get-started-macvlan-zh_CN.md
@@ -6,18 +6,19 @@
 
 本节介绍在建设 AI 集群场景下，如何基于 Macvlan 技术给容器提供 RDMA 通信能力，适用在 RoCE 网络场景下。
 
-基于 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin), 给容器插入 Macvlan 接口，能够把 master 接口的 RDMA 设备共享给容器使用，因此：
+基于 [RDMA shared device plugin](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin)，给容器插入 Macvlan 接口，能够把 master 接口的 RDMA 设备共享给容器使用，因此：
 
 - RDMA system 需要工作在 shared 模式下，所有的容器共享使用宿主机上的 master 网卡的 RDMA 设备。它的特点是，每个新启动的容器中，其 RDMA 设备的可用 GID index 总是在递增变换的，不是固定值。
 
 - 在 Infiniband 的 IPOIB 网卡上不支持创建 Macvlan 接口，因此，本方案只能适用在 RoCE 网络场景下，不能使用在 infiniband 网络场景下。
 
 ## 方案
 
-本文将以如下典型的 AI 集群拓扑为例，介绍如何搭建 Spiderpool
+本文将以如下典型的 AI 集群拓扑为例，介绍如何搭建 Spiderpool。
 
 ![AI Cluster](../../../images/ai-cluster.png)
-图1 AI 集群拓扑
+
+图 1. AI 集群拓扑
 
 集群的网络规划如下：
 
@@ -34,7 +35,7 @@
 - 安装好 Kubernetes 集群，kubelet 工作在图 1 中的主机 eth0 网卡上
 
 - 安装 Calico 作为集群的缺省 CNI，使用主机的 eth0 网卡作为 calico 的流量转发网卡。
-  如果未安装，可参考 [官方文档](https://docs.tigera.io/calico/latest/getting-started/kubernetes/) 或参考以下命令安装:
+  如果未安装，可参考[官方文档](https://docs.tigera.io/calico/latest/getting-started/kubernetes/)或参考以下命令安装：
 
     ```shell
     $ kubectl apply -f https://github.com/projectcalico/calico/blob/master/manifests/calico.yaml
@@ -49,14 +50,14 @@
 
 1. 安装 RDMA 网卡驱动
 
-   对于 Mellanox 网卡，可下载 [NVIDIA OFED 官方驱动](https://network.nvidia.com/products/infiniband-drivers/linux/mlnx_ofed/) 进行主机安装，执行如下安装命令
+    对于 Mellanox 网卡，可下载 [NVIDIA OFED 官方驱动](https://network.nvidia.com/products/infiniband-drivers/linux/mlnx_ofed/)进行主机安装，执行如下安装命令：
 
-    ```
+    ```shell
     $ mount /root/MLNX_OFED_LINUX-24.01-0.3.3.1-ubuntu22.04-x86_64.iso   /mnt
     $ /mnt/mlnxofedinstall --all
     ```
 
-   对于 Mellanox 网卡，也可基于容器化安装驱动，实现对集群主机上所有 Mellanox 网卡批量安装驱动，运行如下命令，注意的是，该运行过程中需要访问因特网获取一些安装包。当所有的 ofed pod 进入 ready 状态，表示主机上已经完成了 OFED driver 安装
+    对于 Mellanox 网卡，也可基于容器化安装驱动，实现对集群主机上所有 Mellanox 网卡批量安装驱动，运行如下命令，注意的是，该运行过程中需要访问因特网获取一些安装包。当所有的 ofed pod 进入 ready 状态，表示主机上已经完成了 OFED driver 安装。
 
     ```shell
     $ helm repo add spiderchart https://spidernet-io.github.io/charts
@@ -73,7 +74,7 @@
 
 2. 确认网卡支持 Ethernet 工作模式
 
-   本示例环境中，宿主机上接入了 mellanox ConnectX 5 VPI 网卡，查询 RDMA 设备，确认网卡驱动安装完成
+    本示例环境中，宿主机上接入了 mellanox ConnectX 5 VPI 网卡，查询 RDMA 设备，确认网卡驱动安装完成
 
     ```
     $ rdma link
@@ -82,21 +83,21 @@
       ....... 
     ```
 
-   确认网卡的工作模式，如下输出表示网卡工作在 Ethernet 模式下，可实现 RoCE 通信
+    确认网卡的工作模式，如下输出表示网卡工作在 Ethernet 模式下，可实现 RoCE 通信
 
     ```
     $ ibstat mlx5_0 | grep "Link layer"
        Link layer: Ethernet
     ```
 
-   如下输出表示网卡工作在 Infiniband 模式下，可实现 Infiniband 通信
+    如下输出表示网卡工作在 Infiniband 模式下，可实现 Infiniband 通信
 
     ```
     $ ibstat mlx5_0 | grep "Link layer"
        Link layer: InfiniBand
     ```
 
-   如果网卡没有工作在预期的模式下，请输入如下命令，确认网卡支持配置 LINK_TYPE 参数，如果没有该参数，请更换支持的网卡型号
+    如果网卡没有工作在预期的模式下，请输入如下命令，确认网卡支持配置 LINK_TYPE 参数，如果没有该参数，请更换支持的网卡型号
 
     ```
     $ mst start
@@ -114,21 +115,21 @@
 
 3. 开启 [GPUDirect RMDA](https://docs.nvidia.com/cuda/gpudirect-rdma/) 功能
 
-   在安装或使用 [gpu-operator](https://github.com/NVIDIA/gpu-operator) 过程中
+    在安装或使用 [gpu-operator](https://github.com/NVIDIA/gpu-operator) 过程中
 
-   a. 开启 helm 安装选项: `--set driver.rdma.enabled=true --set driver.rdma.useHostMofed=true`，gpu-operator 会安装 [nvidia-peermem](https://network.nvidia.com/products/GPUDirect-RDMA/) 内核模块，启用 GPUDirect RMDA 功能，加速 GPU 和 RDMA 网卡之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
+    1. 开启 helm 安装选项: `--set driver.rdma.enabled=true --set driver.rdma.useHostMofed=true`，gpu-operator 会安装 [nvidia-peermem](https://network.nvidia.com/products/GPUDirect-RDMA/) 内核模块，启用 GPUDirect RMDA 功能，加速 GPU 和 RDMA 网卡之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
 
-    ```
-    $ lsmod | grep nvidia_peermem
-      nvidia_peermem         16384  0
-    ```
+        ```
+        $ lsmod | grep nvidia_peermem
+          nvidia_peermem         16384  0
+        ```
 
-   b. 开启 helm 安装选项: `--set gdrcopy.enabled=true`，gpu-operator 会安装 [gdrcopy](https://developer.nvidia.com/gdrcopy) 内核模块，加速 GPU 显存 和 CPU 内存 之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
+    2. 开启 helm 安装选项: `--set gdrcopy.enabled=true`，gpu-operator 会安装 [gdrcopy](https://developer.nvidia.com/gdrcopy) 内核模块，加速 GPU 显存 和 CPU 内存 之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
 
-    ```
-    $ lsmod | grep gdrdrv
-      gdrdrv                 24576  0
-    ```
+        ```
+        $ lsmod | grep gdrdrv
+          gdrdrv                 24576  0
+        ```
 
 4. 确认主机上的 RDMA 子系统为 shared 模式，这是 macvlan 场景下提供 RDMA 设备给容器的要求。 
 
@@ -142,7 +143,7 @@
 
 1. 使用 helm 安装 Spiderpool，并启用 SR-IOV 组件
 
-    ```
+    ```shell
     $ helm repo add spiderpool https://spidernet-io.github.io/spiderpool
     $ helm repo update spiderpool
     $ kubectl create namespace spiderpool
@@ -153,7 +154,7 @@
 
    完成后，安装的组件如下
 
-    ```
+    ```shell
     $ kubectl get pod -n spiderpool
         spiderpool-agent-9sllh                         1/1     Running     0          1m
         spiderpool-agent-h92bv                         1/1     Running     0          1m
@@ -165,9 +166,9 @@
 
 2. 配置 k8s-rdma-shared-dev-plugin, 识别出每个主机上的 RDMA 共享设备资源
 
-   修改如下 configmap，创建出 8 种 RDMA 共享设备，它们分别亲和每一个 GPU 设备。configmap 的详细配置可参考 [官方文档](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin?tab=readme-ov-file#rdma-shared-device-plugin-configurations)
+    修改如下 configmap，创建出 8 种 RDMA 共享设备，它们分别亲和每一个 GPU 设备。configmap 的详细配置可参考[官方文档](https://github.com/Mellanox/k8s-rdma-shared-dev-plugin?tab=readme-ov-file#rdma-shared-device-plugin-configurations)。
 
-    ```
+    ```shell
     $ kubectl edit configmap -n spiderpool spiderpool-rdma-shared-device-plugi
       ....
       config.json: |
@@ -190,9 +191,9 @@
          ]
     ```
 
-    完成如上配置后，可查看 node 的可用资源，确认每个节点都正确识别并上报了 8 种 RDMA 设备资源
+    完成如上配置后，可查看 node 的可用资源，确认每个节点都正确识别并上报了 8 种 RDMA 设备资源。
 
-    ```
+    ```shell
     $ kubectl get no -o json | jq -r '[.items[] | {name:.metadata.name, allocable:.status.allocatable}]'
         [
           {
@@ -213,9 +214,9 @@
 
 3. 创建 CNI 配置和对应的 ippool 资源
 
-   对于 Ethernet 网络，请为所有的 GPU 亲和的 macvlan 网卡配置，并创建对应的 IP 地址池 。 如下例子，配置了 GPU1 亲和的网卡和 IP 地址池
+    对于 Ethernet 网络，请为所有的 GPU 亲和的 macvlan 网卡配置，并创建对应的 IP 地址池。如下例子，配置了 GPU1 亲和的网卡和 IP 地址池。
 
-    ```   
+    ```shell
     $ cat <<EOF | kubectl apply -f -
     apiVersion: spiderpool.spidernet.io/v2beta1
     kind: SpiderIPPool
@@ -246,7 +247,7 @@
 1. 在指定节点上创建一组 DaemonSet 应用
    如下例子，通过 annotations `v1.multus-cni.io/default-network` 指定使用 calico 的缺省网卡，用于进行控制面通信，annotations `k8s.v1.cni.cncf.io/networks` 接入 8 个 GPU 亲和网卡的网卡，用于 RDMA 通信，并配置 8 种 RDMA resources 资源
 
-    ```
+    ```shell
     $ helm repo add spiderchart https://spidernet-io.github.io/charts
     $ helm repo update
     $ helm search repo rdma-tools
@@ -296,16 +297,15 @@
     EOF
 
     $ helm install rdma-tools spiderchart/rdma-tools -f ./values.yaml
-    
     ```
 
-   在容器的网络命名空间创建过程中，Spiderpool 会对 macvlan 接口上的网关进行连通性测试，如果如上应用的所有 POD 都启动成功，说明了每个节点上的 VF 设备的连通性成功，可进行正常的 RDMA 通信。
+    在容器的网络命名空间创建过程中，Spiderpool 会对 macvlan 接口上的网关进行连通性测试，如果如上应用的所有 POD 都启动成功，说明了每个节点上的 VF 设备的连通性成功，可进行正常的 RDMA 通信。
 
 2. 查看容器的网络命名空间状态
 
-   可进入任一一个 POD 的网络命名空间中，确认具备 9 个网卡
+    可进入任一一个 POD 的网络命名空间中，确认具备 9 个网卡：
 
-    ```
+    ```shell
     $ kubectl exec -it rdma-tools-4v8t8  bash
     kubectl exec [POD] [COMMAND] is DEPRECATED and will be removed in a future version. Use kubectl exec [POD] -- [COMMAND] instead.
     root@rdma-tools-4v8t8:/# ip a
@@ -338,7 +338,7 @@
        .....
     ```
 
-   查看路由配置，Spiderpool 会自动为每个网卡调谐策略路由，确保每个网卡上收到的外部请求都会从该网卡上返回回复流量
+    查看路由配置，Spiderpool 会自动为每个网卡调谐策略路由，确保每个网卡上收到的外部请求都会从该网卡上返回回复流量：
 
     ```shell
     root@rdma-tools-4v8t8:/# ip rule
@@ -358,7 +358,7 @@
         default via 172.16.11.254 dev net1
     ```
 
-   main 路由中，确保了 calico 网络流量、ClusterIP 流量、本地宿主机通信等流量都会从 calico 网卡转发
+    main 路由中，确保了 calico 网络流量、ClusterIP 流量、本地宿主机通信等流量都会从 calico 网卡转发
 
     ```
     root@rdma-tools-4v8t8:/# ip r show table main
@@ -378,7 +378,7 @@
         169.254.1.1 dev eth0 scope link
     ```
 
-   确认具备 8 个 RDMA 设备
+    确认具备 8 个 RDMA 设备
 
     ```
     root@rdma-tools-4v8t8:/# rdma link
@@ -391,9 +391,9 @@
 
 3. 在跨节点的 Pod 之间，确认 RDMA 收发数据正常
 
-   开启一个终端，进入一个 Pod 启动服务
+    开启一个终端，进入一个 Pod 启动服务：
 
-    ```
+    ```shell
     # see 8 RDMA devices assigned to the Pod
     $ rdma link
 
@@ -403,7 +403,7 @@
 
    开启一个终端，进入另一个 Pod 访问服务：
 
-    ```
+    ```shell
     # You should be able to see all RDMA network cards on the host
     $ rdma link