Merge pull request #4268 from ty-dc/fix/docs-1104

optimize rdma metrics and podwebhook docs
spidernet-io · Nov 20, 2024 · 335952e · 335952e
2 parents 431e33d + acc8db8
commit 335952e
Show file tree

Hide file tree

Showing 6 changed files with 267 additions and 517 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
@@ -76,7 +76,7 @@
 
     本示例环境中，宿主机上接入了 mellanox ConnectX 5 VPI 网卡，查询 RDMA 设备，确认网卡驱动安装完成
 
-    ```
+    ```shell
     $ rdma link
       link mlx5_0/1 state ACTIVE physical_state LINK_UP netdev ens6f0np0
       link mlx5_1/1 state ACTIVE physical_state LINK_UP netdev ens6f1np1
@@ -85,21 +85,21 @@
 
     确认网卡的工作模式，如下输出表示网卡工作在 Ethernet 模式下，可实现 RoCE 通信
 
-    ```
+    ```shell
     $ ibstat mlx5_0 | grep "Link layer"
        Link layer: Ethernet
     ```
 
     如下输出表示网卡工作在 Infiniband 模式下，可实现 Infiniband 通信
 
-    ```
+    ```shell
     $ ibstat mlx5_0 | grep "Link layer"
        Link layer: InfiniBand
     ```
 
     如果网卡没有工作在预期的模式下，请输入如下命令，确认网卡支持配置 LINK_TYPE 参数，如果没有该参数，请更换支持的网卡型号
 
-    ```
+    ```shell
     $ mst start
 
     # check the card's PCIE 
@@ -119,21 +119,21 @@
 
     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 网卡之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
 
-        ```
+        ```shell
         $ lsmod | grep nvidia_peermem
           nvidia_peermem         16384  0
         ```
 
     2. 开启 helm 安装选项: `--set gdrcopy.enabled=true`，gpu-operator 会安装 [gdrcopy](https://developer.nvidia.com/gdrcopy) 内核模块，加速 GPU 显存 和 CPU 内存 之间的转发性能。可在主机上输入如下命令，确认安装成功的内核模块
 
-        ```
+        ```shell
         $ lsmod | grep gdrdrv
           gdrdrv                 24576  0
         ```
 
 4. 确认主机上的 RDMA 子系统为 shared 模式，这是 macvlan 场景下提供 RDMA 设备给容器的要求。
 
-    ```
+    ```shell
     # Check the current operating mode (the Linux RDMA subsystem operates in shared mode by default):
     $ rdma system
        netns shared copy-on-fork on
@@ -150,11 +150,10 @@
     helm install spiderpool spiderpool/spiderpool -n spiderpool --set rdma.rdmaSharedDevicePlugin.install=true
     ```
 
-    > - 如果您是中国用户，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` 来使用国内的镜像源。
-    > - 设置 `--set spiderpoolAgent.prometheus.enabled --set spiderpoolAgent.prometheus.enabledRdmaMetric=true` 和 `--set grafanaDashboard.install=true` 命令行参数可以开启 RDMA metrics exporter 和 Grafana dashboard，更多可以查看 [RDMA metrics](../../rdma-metrics.md).
-
+    > 如果您是中国用户，可以指定参数 `--set global.imageRegistryOverride=ghcr.m.daocloud.io` 来使用国内的镜像源。
+    > 设置 `--set spiderpoolAgent.prometheus.enabled --set spiderpoolAgent.prometheus.enabledRdmaMetric=true` 和 `--set grafanaDashboard.install=true` 命令行参数可以开启 RDMA metrics exporter 和 Grafana dashboard，更多可以查看 [RDMA metrics](../../rdma-metrics.md).
 
-   完成后，安装的组件如下
+    完成后，安装的组件如下
 
     ```shell
     $ kubectl get pod -n spiderpool
@@ -214,6 +213,8 @@
         ]
     ```
 
+    <a id="create-spiderpool-resource"></a>
+
 3. 创建 CNI 配置和对应的 ippool 资源
 
     对于 Ethernet 网络，请为所有的 GPU 亲和的 macvlan 网卡配置，并创建对应的 IP 地址池。如下例子，配置了 GPU1 亲和的网卡和 IP 地址池。
@@ -237,6 +238,7 @@
       namespace: spiderpool
     spec:
       cniType: macvlan
+      rdmaResourceName: spidernet.io/shared_cx5_gpu1
       macvlan:
         master: ["enp11s0f0np0"]
         ippools:
@@ -247,9 +249,10 @@
 ## 创建测试应用
 
 1. 在指定节点上创建一组 DaemonSet 应用
-   如下例子，通过 annotations `v1.multus-cni.io/default-network` 指定使用 calico 的缺省网卡，用于进行控制面通信，annotations `k8s.v1.cni.cncf.io/networks` 接入 8 个 GPU 亲和网卡的网卡，用于 RDMA 通信，并配置 8 种 RDMA resources 资源
 
-   > 注：可自动为应用注入 RDMA 网络资源，参考 [基于 Webhook 自动注入 RDMA 资源](#基于-webhook-自动注入网络资源)
+    如下例子，通过 annotations `v1.multus-cni.io/default-network` 指定使用 calico 的缺省网卡，用于进行控制面通信，annotations `k8s.v1.cni.cncf.io/networks` 接入 8 个 GPU 亲和网卡的网卡，用于 RDMA 通信，并配置 8 种 RDMA resources 资源
+
+    > 注：可自动为应用注入 RDMA 网络资源，参考 [基于 Webhook 自动注入 RDMA 资源](#基于-webhook-自动注入网络资源)
 
     ```shell
     $ helm repo add spiderchart https://spidernet-io.github.io/charts
@@ -305,6 +308,8 @@
 
     在容器的网络命名空间创建过程中，Spiderpool 会对 macvlan 接口上的网关进行连通性测试，如果如上应用的所有 POD 都启动成功，说明了每个节点上的 VF 设备的连通性成功，可进行正常的 RDMA 通信。
 
+    <a id="checking-pod-network"></a>
+
 2. 查看容器的网络命名空间状态
 
     可进入任一一个 POD 的网络命名空间中，确认具备 9 个网卡：
@@ -364,7 +369,7 @@
 
     main 路由中，确保了 calico 网络流量、ClusterIP 流量、本地宿主机通信等流量都会从 calico 网卡转发
 
-    ```
+    ```shell
     root@rdma-tools-4v8t8:/# ip r show table main
         default via 169.254.1.1 dev eth0
         172.16.11.0/24 dev net1 proto kernel scope link src 172.16.11.10
@@ -384,7 +389,7 @@
 
     确认具备 8 个 RDMA 设备
 
-    ```
+    ```shell
     root@rdma-tools-4v8t8:/# rdma link
         link mlx5_27/1 state ACTIVE physical_state LINK_UP netdev net2
         link mlx5_54/1 state ACTIVE physical_state LINK_UP netdev net1
@@ -405,7 +410,7 @@
     $ ib_read_lat
     ```
 
-   开启一个终端，进入另一个 Pod 访问服务：
+    开启一个终端，进入另一个 Pod 访问服务：
 
     ```shell
     # You should be able to see all RDMA network cards on the host
@@ -417,103 +422,57 @@
 
 ## 基于 Webhook 自动注入网络资源
 
-Spiderpool 为了简化 AI 应用配置多网卡的复杂度，支持通过 annotations (`cni.spidernet.io/rdma-resource-inject`) 对一组网卡配置分类。用户只需要为 Pod 添加相同的注解。这样 Spiderpool 会通过 webhook 自动为 Pod 注入所有具有相同 annotation 的对应的网卡和网络资源。
+在上述步骤中，我们展示了如何使用 SR-IOV 技术在 RoCE 和 Infiniband 网络环境中为容器提供 RDMA 通信能力。然而，当配置多网卡的 AI 应用时，过程会变得复杂。为简化这个过程，Spiderpool 通过 annotations(`cni.spidernet.io/rdma-resource-inject`) 支持对一组网卡配置进行分类。用户只需要为应用添加与网卡配置相同的注解，Spiderpool 就会通过 webhook 自动为应用注入所有具有相同注解的对应网卡和网络资源。
 
-  > 该功能仅支持 [ macvlan,ipvlan,sriov,ib-sriov, ipoib ] 这几种 cniType 的网卡配置。
+> 该功能仅支持 [ macvlan, ipvlan, sriov, ib-sriov, ipoib ] 这几种 cniType 的网卡配置。
 
-1. 安装 Spiderpool 时，指定开启 webhook 自动注入网络资源功能：
+1. 当前 Spiderpool 的 webhook 自动注入 RDMA 网络资源，默认是关闭的，需要手动开启。
 
     ```shell
-    helm install spiderpool spiderchart/spiderpool --set spiderpoolController.podResourceInject.enabled=true
+    ~# helm upgrade --install spiderpool spiderpool/spiderpool --namespace spiderpool --create-namespace --reuse-values --set spiderpoolController.podResourceInject.enabled=true
     ```
 
-    > - 默认关闭 webhook 自动注入网络资源功能，需要用户手动开启。
-    > - 您可以通过 `spiderpoolController.podResourceInject.namespacesExclude` 指定不注入的命名空间，通过 `spiderpoolController.podResourceInject.namespacesInclude` 指定注入的命名空间。
-    > - 安装 Spiderpool 后，您可以通过更新 spiderpool-config configMap 中 podResourceInject 字段更新配置。
-
-2. 创建 SpiderMultusConfig 时指定 labels，并配置 RDMA 相关配置：
-
-    ```shell
-    $ cat <<EOF | kubectl apply -f -
-    apiVersion: spiderpool.spidernet.io/v2beta1
-    kind: SpiderMultusConfig
-    metadata:
-      name: gpu1-macvlan
-      namespace: spiderpool
-      annotations:
-        cni.spidernet.io/rdma-resource-inject: gpu-macvlan
-    spec:
-      cniType: macvlan
-      macvlan:
-        master: ["enp11s0f0np0"]
-        enableRdma: true
-        rdmaResourceName: spidernet.io/shared_cx5_gpu1
-        ippools:
-          ipv4: ["gpu1-net11"]
-    EOF
+    > 启用 webhook 自动注入网络资源功能后，您可以通过更新 configMap: spiderpool-config 中的 podResourceInject 字段更新配置。
+    >
+    > 您可以通过 `podResourceInject.namespacesExclude` 指定不进行 RDMA 网络资源注入的命名空间，通过 `podResourceInject.namespacesInclude` 指定需要进行 RDMA 网络资源注入的命名空间。
+    >
+    > 当前，完成配置变更后，您需要重启 spiderpool-controller 来使配置生效。
+
+    如下的示例中，展示了无需进行 RDMA 网络资源注入的命名空间 `["kube-system", "spiderpool"]`, 需要注入的命名空间 `["test"]`。
+
+    ```yaml
+    apiVersion: v1
+    data:
+      conf.yml: |
+        enableIPv4: true
+        ...
+        podResourceInject:
+          enabled: true
+          namespacesExclude: ["kube-system", "spiderpool"]
+          namespacesInclude: ["test"]
     ```
 
-    > - `cni.spidernet.io/rdma-resource-inject: gpu-macvlan` 固定的 key，value 为用户自定义。
-    > - `enableRdma`, `rdmaResourceName` 和 `ippools` 必须配置，否则 Pod 无法成功注入网络资源。
-
-3. 创建应用时添加注解: `cni.spidernet.io/rdma-resource-inject: gpu-macvlan`，这样 Spiderpool 自动为 Pod 添加  8 个 GPU 亲和网卡的网卡，用于 RDMA 通信，并配置 8 种 RDMA resources 资源:
-
-    > 注意：使用 webhook 自动注入网络资源功能时，不能为应用添加其他网络配置注解(如 `k8s.v1.cni.cncf.io/networks` 和 `ipam.spidernet.io/ippools`等)，否则会影响资源自动注入功能。
-
+2. 如果 AI 应用有多网卡需求，请为需要配置给应用的多个网卡的 SpiderMultusConfig 资源添加如下注解，如何创建 SpiderMultusConfig 资源，请参考[网卡资源创建](#create-spiderpool-resource)：
+  
     ```shell
-    $ helm repo add spiderchart https://spidernet-io.github.io/charts
-    $ helm repo update
-    $ helm search repo rdma-tools
-   
-    # run daemonset on worker1 and worker2
-    $ cat <<EOF > values.yaml
-    # for china user , it could add these to use a domestic registry
-    #image:
-    #  registry: ghcr.m.daocloud.io
+    ~# kubectl annotate SpiderMultusConfig -n [命名空间] [资源名称] "cni.spidernet.io/rdma-resource-inject=gpu-macvlan"
+    # 示例如下：
+    ~# kubectl annotate SpiderMultusConfig -n spiderpool gpu1-macvlan "cni.spidernet.io/rdma-resource-inject=gpu-macvlan"
+    ```
 
-    # just run daemonset in nodes 'worker1' and 'worker2'
-    affinity:
-      nodeAffinity:
-        requiredDuringSchedulingIgnoredDuringExecution:
-          nodeSelectorTerms:
-          - matchExpressions:
-            - key: kubernetes.io/hostname
-              operator: In
-              values:
-              - worker1
-              - worker2
+    > 其中 `cni.spidernet.io/rdma-resource-inject: gpu-macvlan` 的 key：cni.spidernet.io/rdma-resource-inject 是固定的，请不要更改它，而value：gpu-macvlan 可以被用户自定义。
 
-    # macvlan interfaces
-    extraAnnotations:
-      cni.spidernet.io/rdma-resource-inject: gpu-macvlan
-    EOF
+3. 创建 AI 应用时，为应用也添加相同注解: `cni.spidernet.io/rdma-resource-inject: gpu-macvlan`，这样 Spiderpool 可以自动为应用的每个 Pod 添加多个 GPU 亲和的网卡，用于 RDMA 通信，并配置多种 RDMA 资源:
 
-    $ helm install rdma-tools spiderchart/rdma-tools -f ./values.yaml
+    ```yaml
+    ...
+    spec:
+      template:
+        metadata:
+          annotations:
+            cni.spidernet.io/rdma-resource-inject: gpu-macvlan
     ```
 
-    当 Pod 成功 Running，检查 Pod 是否成功注入 8 个 RDMA 网卡的 annotations 和 8 种 RDMA 资源。
+    > 注意：使用 webhook 自动注入网络资源功能时，不能为应用添加其他网络配置注解(如 `k8s.v1.cni.cncf.io/networks` 和 `ipam.spidernet.io ippools`等)，否则会影响资源自动注入功能。
 
-    ```shell
-    # Pod multus annotations
-    k8s.v1.cni.cncf.io/networks: |-
-      [{"name":"gpu1-macvlan","namespace":"spiderpool"},
-      {"name":"gpu2-macvlan","namespace":"spiderpool"},
-      {"name":"gpu3-macvlan","namespace":"spiderpool"},
-      {"name":"gpu4-macvlan","namespace":"spiderpool"},
-      {"name":"gpu5-macvlan","namespace":"spiderpool"},
-      {"name":"gpu6-macvlan","namespace":"spiderpool"},
-      {"name":"gpu7-macvlan","namespace":"spiderpool"},
-      {"name":"gpu8-macvlan","namespace":"spiderpool"}]
-    # macvlan resource
-    resources:
-      requests:
-        spidernet.io/shared_cx5_gpu1: 1
-        spidernet.io/shared_cx5_gpu2: 1
-        spidernet.io/shared_cx5_gpu3: 1
-        spidernet.io/shared_cx5_gpu4: 1
-        spidernet.io/shared_cx5_gpu5: 1
-        spidernet.io/shared_cx5_gpu6: 1
-        spidernet.io/shared_cx5_gpu7: 1
-        spidernet.io/shared_cx5_gpu8: 1
-        #nvidia.com/gpu: 1
-    ```
+    当 Pod 成功 Running，通过进入 Pod 网络命名空间检查 Pod 是否成功被添加了具备相同注解的所有 RDMA 资源，参考[Pod 网络资源检查](#checking-pod-network)