ghcr.io/mellanox/nic-configuration-operator-daemon:v0.1.3

NVIDIA NIC Configuration Operator

NVIDIA NIC Configuration Operator 提供 Kubernetes API（自定义资源定义，Custom Resource Definition），以协调的方式允许在 Nvidia NIC 上进行 FW 配置。它在每个目标节点上部署配置守护进程，以配置那里的 Nvidia NIC。NVIDIA NIC Configuration Operator 在实际配置前使用 Maintenance Operator 准备节点以进行维护。

• numVFs：若提供，将通过 nvconfig 配置 SR-IOV VFs。这是必选参数。例如：若 numVFs=2，则 SRIOV_EN=1 且 SRIOV_NUM_OF_VFS=2；若 numVFs=0，则 SRIOV_EN=0 且 SRIOV_NUM_OF_VFS=0。 numVFs

  • 这是必选参数。
  • 例如：若 numVFs=2，则 SRIOV_EN=1 且 SRIOV_NUM_OF_VFS=2。 numVFs=2 SRIOV_EN=1 SRIOV_NUM_OF_VFS=2
  • 若 numVFs=0，则 SRIOV_EN=0 且 SRIOV_NUM_OF_VFS=0。 numVFs=0 SRIOV_EN=0 SRIOV_NUM_OF_VFS=0

• linkType：若提供，将为所有 NIC 端口配置 NIC 的链路类型。这是必选参数。例如，若 linkType = Infiniband，则设置 LINK_TYPE_P1=IB；若存在第二个 PCI 功能，则同时设置 LINK_TYPE_P2=IB。 linkType

  • 这是必选参数。
  • 例如，若 linkType = Infiniband，则设置 LINK_TYPE_P1=IB；若存在第二个 PCI 功能，则同时设置 LINK_TYPE_P2=IB。 linkType = Infiniband LINK_TYPE_P1=IB LINK_TYPE_P2=IB

• pciPerformanceOptimized：执行 PCI 性能优化。若启用，默认将执行以下操作：

  • 设置 nvconfig 参数 MAX_ACC_OUT_READ 为 0（使用设备默认值） MAX_ACC_OUT_READ
  • 为每个 PF 设置 PCI 最大读请求大小为 4096（注意：这是运行时配置，不持久化） 4096
  • 用户可通过 maxAccOutRead 和 maxReadRequest 覆盖值 maxAccOutRead maxReadRequest

[!IMPORTANT] 根据 PRM，将 MAX_ACC_OUT_READ 设置为 0 会启用自动模式，应用最合适的优化。但在某些固件版本中存在 bug，导致无法使用 0 值。在此情况下，在修复可用前，MAX_ACC_OUT_READ 将不被设置，并会为该设备的 CR 发出警告事件。

• 根据 PRM，将 MAX_ACC_OUT_READ 设置为 0 会启用自动模式，应用最合适的优化。但在某些固件版本中存在 bug，导致无法使用 0 值。 MAX_ACC_OUT_READ

• 在此情况下，在修复可用前，MAX_ACC_OUT_READ 将不被设置，并会为该设备的 CR 发出警告事件。 MAX_ACC_OUT_READ

• roceOptimized：执行 RoCE 相关优化。若启用，默认执行以下操作：

  • 为两个端口设置 Nvconfig（可从 PF0 应用）；若存在第二个端口，则有条件地应用于第二个端口
    • ROCE_CC_PRIO_MASK_P1=255，ROCE_CC_PRIO_MASK_P2=255
    • CNP_DSCP_P1=4，CNP_DSCP_P2=4
    • CNP_802P_PRIO_P1=6，CNP_802P_PRIO_P2=6
  • 若存在第二个端口，则有条件地应用于第二个端口
    • ROCE_CC_PRIO_MASK_P1=255，ROCE_CC_PRIO_MASK_P2=255
    • CNP_DSCP_P1=4，CNP_DSCP_P2=4
    • CNP_802P_PRIO_P1=6，CNP_802P_PRIO_P2=6
  • ROCE_CC_PRIO_MASK_P1=255，ROCE_CC_PRIO_MASK_P2=255 ROCE_CC_PRIO_MASK_P1=255 ROCE_CC_PRIO_MASK_P2=255
  • CNP_DSCP_P1=4，CNP_DSCP_P2=4 CNP_DSCP_P1=4 CNP_DSCP_P2=4
  • CNP_802P_PRIO_P1=6，CNP_802P_PRIO_P2=6 CNP_802P_PRIO_P1=6 CNP_802P_PRIO_P2=6
  • 为优先级 3 配置 PFC（优先级流控制），在每个 PF 上设置信任模式为 dscp，将 ToS（服务类型）设置为 0。非持久化（需在每次启动后应用）
  • 非持久化（需在每次启动后应用）
  • 用户可通过 trust、pfc 和 tos 参数覆盖值 trust pfc tos
  • 仅当 linkType=Ethernet 时可启用 linkType=Ethernet

• gpuDirectOptimized：执行 GPU Direct 优化。目前仅支持裸机环境的优化。若启用，执行以下操作：

  • 设置 nvconfig ATS_ENABLED=0 ATS_ENABLED=0
  • 仅当 pciPerformanceOptimized 启用时可启用 pciPerformanceOptimized
  • 允许使用 NVConfig 支持的数值及其字符串别名（例如 REAL_TIME_CLOCK_ENABLE=False、REAL_TIME_CLOCK_ENABLE=0）。 REAL_TIME_CLOCK_ENABLE=False REAL_TIME_CLOCK_ENABLE=0
  • 对于每端口参数（后缀 _P1、_P2），若设备为单端口，则忽略带 _P2 后缀的参数。 _P1 _P2 _P2

• spectrumXOptimized：启用 Spectrum-X 特定 NIC 优化。启用时：

  • 要求 linkType=Ethernet 且 numVfs=1 linkType=Ethernet numVfs=1
  • 不能与 roceOptimized 同时启用（RoCE 设置会自动包含） roceOptimized
  • 可与 rawNvConfig 结合使用——原始参数将作为覆盖项合并到 Spectrum-X 计算的参数之上 rawNvConfig
  • 仅支持 ConnectX-8（nicType: 1023）、ConnectX-9（nicType: 1025）和 BlueField-3 SuperNIC（nicType: a2dc） nicType: 1023 nicType: 1025 nicType: a2dc
  • version：必选。参考架构版本（RA1.3、RA2.0、RA2.1 或 RA2.2） version RA1.3 RA2.0 RA2.1 RA2.2
  • overlay：可选，默认 none。设置为 l3 以启用 L3 E*** 覆盖网络 overlay none l3
  • multiplaneMode：可选，默认 none。仅在 RA2.1 中可用。选项：none、swplb、hwplb、uniplane multiplaneMode none none swplb hwplb uniplane
  • numberOfPlanes：可选，默认 1。仅在 RA2.1 中可用。选项：1、2

NIC配置操作员支持针对不同版本NVIDIA Spectrum-X参考架构（RA1.3、RA2.0和RA2.1）的Spectrum-X特定NIC配置。

Spectrum-X支持的NIC类型：

• ConnectX-8（设备ID 1023）——支持所有多平面模式
  1023- ConnectX-9（设备ID 1025）——支持所有多平面模式（与ConnectX-8配置相同）
  1025- BlueField-3 SuperNIC（设备ID a2dc）——支持除hwplb外的所有多平面模式
  a2dc``hwplbRA2.1引入了多平面模式支持，允许NIC配置多个数据平面。可用模式：

none``swplb``hwplb``uniplane> [!NOTE] 多平面模式仅在RA2.1中可用。对于RA1.3和RA2.0，multiplaneMode必须为none，numberOfPlanes必须为1。

[!NOTE] 多平面模式仅在RA2.1中可用。对于RA1.3和RA2.0，multiplaneMode必须为none，numberOfPlanes必须为1。

multiplaneMode``none``numberOfPlanes## 带多平面的Spectrum-X NicConfigurationTemplate示例：

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicConfigurationTemplate
metadata:
name: spectrum-x-multiplane-configuration
namespace: nvidia-network-operator
spec:
nodeSelector:
feature.node.kubernetes.io/network-sriov.capable: "true"
nicSelector:
nicType: "1023" # ConnectX-8。ConnectX-9使用"1025"，BlueField-3 SuperNIC使用"a2dc"（BF3不支持hwplb）
# partNumbers:
# - "MCX713106AEHEA_QP1"
template:
numVfs: 1
linkType: Ethernet
spectrumXOptimized:
enabled: true
version: "RA2.1"
overlay: "none"
multiplaneMode: "hwplb" # 硬件数据包负载均衡，仅ConnectX-8支持
numberOfPlanes: 4

NicFirmwareSource

NICFirmwareSource CR表示包含NIC固件二进制档案的URL源列表。

为NIC固件升级配置存储类

要启用NIC固件升级功能，NIC集群策略中应提供NicFirmwareStorage部分。可以选择创建新的PVC或使用现有PVC。固件二进制文件将由供应器控制器供应，该控制器将监视NICFirmwareSource对象，并在给定存储类启用的共享卷中供应二进制文件。节点代理需要确保引用的NICFirmwareSource对象已完全协调（status.state == Success），然后再进行固件更新。

NicFirmwareStorage## 存储类部署示例

要在集群中设置持久NFS存储，可以使用CSI NFS驱动程序仓库中的示例。部署NFS服务器和NFS CSI驱动程序后，应部署存储类。然后可以将存储类的名称传递给NIC集群策略。

NICFirmwareSource示例：

# 请先修改此模板，它仅提供配置示例
apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicFirmwareSource
metadata:
name: connectx-6dx-firmware-22-44-1036
namespace: network-operator
finalizers:
- configuration.net.nvidia.com/nic-configuration-operator
spec:
# 来自Mellanox网站的固件二进制列表（如果是压缩包，需解压后放置）
binUrlSources:
- https://www.mellanox.com/downloads/firmware/fw-ConnectX6Dx-rel-22_44_1036-MCX623106AC-CDA_Ax-UEFI-14.37.14-FlexBoot-3.7.500.signed.bin.zip
bfbUrlSource: https://example.com/bluefield3-31.41.0.bfb
status:
state: Success
binaryVersions:
22.44.1036:
- mt_0000000436
bfbVersions:
a2dc: 34.41.0 # BF3 NIC固件
a2d6: 25.21.0 # BF2 NIC固件

NICFirmwareTemplate

NICFirmwareTemplate CRD用于从引用的NICFirmwareSource为部分设备请求固件验证或更新。

NIC配置操作员将选择集群中与模板选择器匹配的NIC设备，并对其应用配置规范。

如果多个模板匹配单个设备，则不会应用任何模板，并且错误将在所有模板的状态中报告。

有关更多信息，请参阅api-reference。

NICFirmwareTemplate示例：

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicFirmwareTemplate
metadata:
name: connectx6dx-config
namespace: network-operator
spec:
nodeSelector:
kubernetes.io/hostname: cloud-dev-41
nicSelector:
nicType: "101d"
# partNumbers:
# - "MCX713106AEHEA_QP1"
template:
nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036
updatePolicy: Update

NICDevice

NICDevice CRD由配置守护进程自动创建，表示特定K8s节点上的特定NVIDIA NIC。设备名称组合了节点名称、设备类型及其PCI设备地址（Domain:Bus:Device，其中:和.替换为-）。使用PCI设备地址确保唯一性，因为在共享闪存VPD镜像的嵌入式NIC系统（例如HGX B300）上，序列号不能保证唯一。

Domain:Bus:DeviceFirmwareUpdateInProgress状态条件可用于跟踪特定设备上的固件验证/更新状态。如果固件更新过程中发生错误，将在此字段中反映。ConfigUpdateInProgress状态条件可用于跟踪特定设备上的固件配置更新状态。如果固件配置更新过程中发生错误，将在此字段中反映。

FirmwareUpdateInProgress``ConfigUpdateInProgress有关更多信息，请参阅api-reference。

NICDevice示例

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicDevice
metadata:
name: co-node-25-101b-0000-04-00
namespace: nic-configuration-operator
spec:
firmware:
nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036
updatePolicy: Update
configuration:
template:
linkType: Ethernet
numVfs: 8
pciPerformanceOptimized:
enabled: true
status:
conditions:
- reason: DeviceFirmwareConfigMatch
type: FirmwareUpdateInProgress
status: "False"
message: Firmware matches the requested version
- reason: UpdateSuccessful
type: ConfigUpdateInProgress
status: "False"
firmwareVersion: 20.42.1000
node: co-node-25
partNumber: mcx632312a-hdat
ports:
- networkInterface: enp4s0f0np0
pci: "0000:04:00.0"
rdmaInterface: mlx5_0
- networkInterface: enp4s0f1np1
pci: "0000:04:00.1"
rdmaInterface: mlx5_1
psid: mt_0000000225
serialNumber: mt2232t13210
type: 101b

实现细节：

NicDevice CRD由配置守护进程创建和协调。协调逻辑方案可在此处找到。

NicInterfaceNameTemplate

NicInterfaceNameTemplate CRD允许您为Spectrum-X NIC上的RDMA和网络设备接口定义自定义命名模式。这在需要可预测接口命名的多平面和多通道部署中非常有用。

操作顺序

要将NIC配置操作符纳入网络配置工作流，可能需要强制执行严格的操作顺序。例如，SR-IOV网络配置守护进程pod应在NIC配置守护进程完成后启动。为了向依赖NIC配置的pod指示配置是否正在进行，操作符会管理nvidia.com/operator.nic-configuration.wait标签：当请求的NIC配置成功应用时，该标签值为false；当NIC配置正在进行时，该标签值为true。要使用此机制，工作流中的后续pod可以将nvidia.com/operator.nic-configuration.wait=false添加到其节点标签选择器中。这样，在配置NIC时，这些pod会自动从节点驱逐。

NIC配置守护进程本身依赖节点上存在network.nvidia.com/operator.mofed.wait=false标签，因为它需要DOCA-OFED驱动运行以进行某些配置。

Spectrum-X 配置

NIC 配置操作器支持针对不同版本的 NVIDIA Spectrum-X 参考架构（RA1.3、RA2.0 和 RA2.1）的 Spectrum-X 特定 NIC 配置。

Spectrum-X 支持的 NIC 类型：

• ConnectX-8（设备 ID 1023）——支持所有多平面模式
• ConnectX-9（设备 ID 1025）——支持所有多平面模式（与 ConnectX-8 配置相同）
• BlueField-3 SuperNIC（设备 ID a2dc）——支持除 hwplb 外的所有多平面模式

RA2.1 引入了多平面模式支持，允许将 NIC 配置为具有多个数据平面。可用模式：

[!NOTE] 多平面模式仅在 RA2.1 中可用。对于 RA1.3 和 RA2.0，multiplaneMode 必须设为 none，numberOfPlanes 必须设为 1。

带多平面的 Spectrum-X NicConfigurationTemplate 示例：

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicConfigurationTemplate
metadata:
name: spectrum-x-multiplane-configuration
namespace: nvidia-network-operator
spec:
nodeSelector:
feature.node.kubernetes.io/network-sriov.capable: "true"
nicSelector:
nicType: "1023" # ConnectX-8。ConnectX-9 使用 "1025"，BlueField-3 SuperNIC 使用 "a2dc"（BF3 不支持 hwplb）
# partNumbers:
# - "MCX713106AEHEA_QP1"
template:
numVfs: 1
linkType: Ethernet
spectrumXOptimized:
enabled: true
version: "RA2.1"
overlay: "none"
multiplaneMode: "hwplb" # 硬件数据包负载均衡，仅 ConnectX-8 支持
numberOfPlanes: 4

NicFirmwareSource

NICFirmwareSource CR 表示包含 NIC 固件二进制档案的 URL 源列表。

为 NIC 固件升级配置存储类

要启用 NIC 固件升级功能，应在 https://github.com/Mellanox/network-operator/blob/7c31e789835afdad114b1a68011e5307bc773bcf/api/v1alpha1/nicclusterpolicy_types.go#L321 中提供 NicFirmwareStorage 部分。可以选择创建新的 PVC 或使用现有 PVC。 固件二进制文件将由供应器控制器供应，该控制器将监控 NICFirmwareSource 对象，并在由指定存储类启用的共享卷中供应二进制文件。 节点代理需要确保引用的 NICFirmwareSource 对象已完全协调（status.state == Success），然后再进行固件更新。

存储类部署示例

要在集群中设置持久 NFS 存储，可以使用 https://github.com/kubernetes-csi/csi-driver-nfs/blob/master/deploy/example/nfs-provisioner/README.md%E3%80%82 部署 NFS 服务器和 NFS CSI 驱动后，应部署 https://github.com/kubernetes-csi/csi-driver-nfs/blob/master/deploy/example/storageclass-nfs.yaml%E3%80%82%E7%84%B6%E5%90%8E%E5%8F%AF%E4%BB%A5%E5%B0%86%E5%AD%98%E5%82%A8%E7%B1%BB%E7%9A%84%E5%90%8D%E7%A7%B0%E4%BC%A0%E9%80%92%E7%BB%99 NIC 集群策略。

NICFirmwareSource 示例：

NICFirmwareTemplate

NICFirmwareTemplate CRD 用于从引用的 NICFirmwareSource 为部分设备请求固件验证或更新。

NIC 配置操作器将选择集群中与模板选择器匹配的 NIC 设备，并对其应用配置规范。

如果多个模板匹配单个设备，则不会应用任何模板，且所有相关模板的状态中都会报告错误。

有关更多信息，请参阅 api-reference。

NICFirmwareTemplate 示例：

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicFirmwareTemplate
metadata:
name: connectx6dx-config
namespace: network-operator
spec:
nodeSelector:
kubernetes.io/hostname: cloud-dev-41
nicSelector:
nicType: "101d"
# partNumbers:
# - "MCX713106AEHEA_QP1"
template:
nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036
updatePolicy: Update

NICDevice

NICDevice CRD 由配置守护进程自动创建，代表特定 K8s 节点上的特定 NVIDIA NIC。 设备名称由节点名称、设备类型及其 PCI 设备地址（Domain:Bus:Device，其中 : 和 . 替换为 -）组合而成。使用 PCI 设备地址确保唯一性，因为在共享闪存 VPD 镜像的嵌入式 NIC 系统（如 HGX B300）上，序列号不能保证唯一。

FirmwareUpdateInProgress 状态条件可用于跟踪特定设备上固件验证/更新的状态。如果固件更新过程中发生错误，将在此字段中反映。 ConfigUpdateInProgress 状态条件可用于跟踪特定设备上固件配置更新的状态。如果固件配置更新过程中发生错误，将在此字段中反映。

有关更多信息，请参阅 api-reference。

NICDevice 示例

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicDevice
metadata:
name: co-node-25-101b-0000-04-00
namespace: nic-configuration-operator
spec:
firmware:
nicFirmwareSourceRef: connectx6dx-firmware-22-44-1036
updatePolicy: Update
configuration:
template:
linkType: Ethernet
numVfs: 8
pciPerformanceOptimized:
enabled: true
status:
conditions:
- reason: DeviceFirmwareConfigMatch
type: FirmwareUpdateInProgress
status: "False"
message: Firmware matches the requested version
- reason: UpdateSuccessful
type: ConfigUpdateInProgress
status: "False"
firmwareVersion: 20.42.1000
node: co-node-25
partNumber: mcx632312a-hdat
ports:
- networkInterface: enp4s0f0np0
pci: "0000:04:00.0"
rdmaInterface: mlx5_0
- networkInterface: enp4s0f1np1
pci: "0000:04:00.1"
rdmaInterface: mlx5_1
psid: mt_0000000225
serialNumber: mt2232t13210
type: 101b

实现细节：

NICDevice CRD 由配置守护进程创建和协调。协调逻辑示意图可在 此处 找到。

NicInterfaceNameTemplate

NicInterfaceNameTemplate CRD 允许您为 Spectrum-X NIC 上的 RDMA 和网络设备接口定义自定义命名模式。这在需要可预测接口命名的多平面和多rail部署中非常有用。

操作器会在主机上部署 udev 规则，根据指定的命名模板重命名网络和 RDMA 接口。

模板使用以下占位符构建设备名称：

• %nic_id%：NIC 在扁平化 NIC 列表中的索引
• %plane_id%：特定 NIC 的平面索引
• %rail_id%：给定 NIC 所属的 rail 索引

NicInterfaceNameTemplate 示例：

apiVersion: configuration.net.nvidia.com/v1alpha1
kind: NicInterfaceNameTemplate
metadata:
name: spectrum-x-interface-names
namespace: nvidia-network-operator
spec:
pfsPerNic: 2
rdmaDevicePrefix: "rdma_%nic_id%_%plane_id%_%rail_id%"
netDevicePrefix: "net_%nic_id%_%plane_id%_%rail_id%"
railPciAddresses:
- ["0000:1a:00.0", "0000:2a:00.0"]
- ["0000:3a:00.0", "0000:4a:00.0"]

railPciAddresses 字段定义 PCI 地址到 rail 的映射。第一维度是 rail 索引，第二维度是该 rail 中 NIC 的 PCI 地址列表。

生成的 udev 规则

操作器根据模板生成 udev 规则并写入主机。规则写入两个单独的文件：

网络设备的生成 udev 规则示例（/etc/udev/rules.d/10-nic-net-interface-naming.rules）：

# Auto-generated by nic-configuration-operator
# Do not edit manually

SUBSYSTEM=="net", ACTION=="add", KERNELS=="0000:1a:00.0", NAME="net_0_0_0"
SUBSYSTEM=="net", ACTION=="add", KERNELS=="0000:1a:00.1", NAME="net_0_1_0"
SUBSYSTEM=="net", ACTION=="add", KERNELS=="0000:3a:00.0", NAME="net_1_0_1"
SUBSYSTEM=="net", ACTION=="add", KERNELS=="0000:3a:00.1", NAME="net_1_1_1"

RDMA 设备的生成 udev 规则示例（/etc/udev/rules.d/10-nic-rdma-interface-naming.rules）：

# Auto-generated by nic-configuration-operator
# Do not edit manually

ACTION=="add", KERNELS=="0000:1a:00.0", SUBSYSTEM=="infiniband", RUN+="/usr/bin/rdma dev set %k name rdma_0_0_0"
ACTION=="add", KERNELS=="0000:1a:00.1", SUBSYSTEM=="infiniband", RUN+="/usr/bin/rdma dev set %k name rdma_0_1_0"
ACTION=="add", KERNELS=="0000:3a:00.0", SUBSYSTEM=="infiniband", RUN+="/usr/bin/rdma dev set %k name rdma_1_0_1"
ACTION=="add", KERNELS=="0000:3a:00.1", SUBSYSTEM=="infiniband", RUN+="/usr/bin/rdma dev set %k name rdma_1_1_1"

操作顺序