ghcr.io/k8snetworkplumbingwg/sriov-network-device-plugin:1d67737c94735fced82d9241c82fba7801353eb1

Kubernetes 的 SR-IOV 网络设备插件

目录

• Kubernetes 的 SR-IOV 网络设备插件
• 目录
• SR-IOV 网络设备插件
• 功能特性
• 支持的 SR-IOV 网卡
• 快速入门
• 创建 SR-IOV 虚拟功能
• 安装 SR-IOV CNI
• 获取 SR-IOV 网络设备插件容器镜像
• 安装 SR-IOV 网络设备插件
• 安装一个兼容的 CNI 元插件
• 配置
• 配置参数
• 命令行参数
• 假设条件
• 工作流程
• 示例部署
• 部署设备插件
• 使用 Multus 时部署 SR-IOV 工作负载
• 使用 DANM 时部署 SR-IOV 工作负载
• Pod 设备信息
• 虚拟部署支持
• 在虚拟环境中配置设备插件扩展选择器
• 虚拟环境中的 CNI 插件
• 无 IOMMU 的虚拟环境
• 多架构支持
• 容器设备接口
• 问题与贡献

SR-IOV 网络设备插件

SR-IOV 网络设备插件是 Kubernetes 的设备插件，用于发现和公布以下形式的网络资源：

• SR-IOV 虚拟功能（VF）
• PCI 物理功能（PF）
• 辅助网络设备，特别是子功能（SF）

这些资源在 Kubernetes 节点上可用。

功能特性

• 处理支持/不支持 SR-IOV 的设备（包括网卡和加速器）
• 处理基于 PCI 的辅助网络设备（目前仅支持 SF）
• 支持具有内核和用户空间（UIO 和 VFIO）驱动程序的设备
• 允许使用“选择器（selector）”进行资源分组
• 用户可配置的 resourceName
• 检测 Kubelet 重启并自动重新注册
• 检测链路状态（适用于 Linux 网络设备）并相应更新关联 VF 的健康状态
• 可扩展以支持新的设备类型（如尚未支持，只需最少工作量）
• 适用于不具备虚拟化 IOMMU 支持的 Kubernetes 虚拟部署（VFIO No-IOMMU 支持）

要部署使用 SR-IOV VF、辅助网络设备或 PCI PF 的工作负载，此插件需要与以下两个 CNI 组件配合使用：

• 任何支持基于设备插件的网络配置的 CNI 元插件（Multus CNI 或 DANM）
  • 检索 Pod 的已分配网络设备信息
• 能够使用分配给 Pod 的网络设备的 CNI
  • SR-IOV CNI（适用于 SR-IOV VF）
    • 在 Pod 创建期间，使用元插件提供的 VF 信息将已分配的 SR-IOV VF 接入 Pod 的网络命名空间
    • 在 Pod 删除期间，重置并从 Pod 释放 VF
  • 主机设备 CNI（适用于 PCI PF）
    • 在 Pod 创建期间，使用元插件提供的设备信息将已分配的网络设备接入 Pod 的网络命名空间
    • 在 Pod 删除期间，重置并从 Pod 释放已分配的网络设备

有关 Kubernetes 中的多网络接口支持，请遵循快速入门。

支持的 SR-IOV 网卡

以下网卡已通过此实现的测试。不过，其他支持 SR-IOV 的网卡也应能正常工作。

• Intel® Ethernet 800 Series（E810）
• Intel® Ethernet 700 Series（XL710、X710、XXV710）
• Intel® Ethernet 500 Series（82599、X520、X540、X550）
• Mellanox ConnectX-4®
• Mellanox ConnectX-4® Lx EN 适配器
• Mellanox ConnectX-5®
• Mellanox ConnectX-5® Ex
• Mellanox ConnectX-6®
• Mellanox ConnectX-6® Dx
• Mellanox BlueField-2®
• Broadcom NetXtreme-E Series Adapters

快速入门

创建网络功能

在启动 SR-IOV 网络设备插件之前，您需要在系统上创建所需的网络功能。以下文档将指导您完成该过程。

• 创建 SR-IOV 虚拟功能
• 创建子功能

安装 SR-IOV CNI

有关构建和安装说明，请参见 https://github.com/k8snetworkplumbingwg/sriov-cni 仓库。支持 SR-IOV CNI 2.0+ 版本。

获取 SR-IOV 网络设备插件容器镜像

GitHub

docker pull ghcr.io/k8snetworkplumbingwg/sriov-network-device-plugin:latest

本地构建镜像

make image

[!NOTE] 构建成功后，将创建一个标签为 ghcr.io/k8snetworkplumbingwg/sriov-network-device-plugin:latest 的 docker 镜像。您需要在每个节点上构建此镜像。或者，您可以使用本地 docker 仓库来托管此镜像。

安装 SR-IOV 网络设备插件

部署配置映射

创建定义 SR-IOV 资源池配置的 ConfigMap

[!IMPORTANT] 确保更新 configMap 数据中的 'config.json' 条目，以反映设备插件的资源配置。有关支持的配置参数，请参见配置部分。

kubectl create -f deployments/configMap.yaml

部署守护进程集

kubectl create -f deployments/sriovdp-daemonset.yaml

安装一个兼容的 CNI 元插件

需要安装兼容的 CNI 元插件，以便 SR-IOV CNI 插件能够获取已分配 VF 的 deviceID 进行配置。

选项 1 - Multus

安装 Multus

请参考 Multus 的https://github.com/k8snetworkplumbingwg/multus-cni#quickstart-installation-guide%E6%9D%A5%E5%AE%89%E8%A3%85 Multus。

网络对象 CRD

Multus 使用自定义资源定义（CRD）来定义额外的网络附件。这些网络附件 CRD 遵循 Kubernetes 网络 Plumbing 工作组（NPWG）定义的标准。有关更多信息，请参考https://github.com/k8snetworkplumbingwg/multus-cni/blob/master/README.md%E3%80%82

1. 创建 SR-IOV 网络 CRD

kubectl create -f deployments/sriov-crd.yaml

选项 2 - DANM

本节介绍如果选择 DANM 作为元插件，在 Kubernetes 中部署 SR-IOV 网络设备插件的示例。

安装 DANM

有关详细说明，请参考 https://github.com/nokia/danm/blob/master/deployment-guide.md%E3%80%82

创建 SR-IOV 类型网络

DANM 支持基于设备插件（Device Plugin）的动态级别 SR-IOV 配置。有关详细说明，请参阅 https://github.com/nokia/danm/blob/master/user-guide.md%E3%80%82%E6%9C%89%E5%85%B3%E7%A4%BA%E4%BE%8B%E6%B8%85%E5%8D%95%E5%AF%B9%E8%B1%A1%EF%BC%8C%E8%AF%B7%E5%8F%82%E8%80%83 https://github.com/nokia/danm/tree/master/example/device_plugin_demo

请参阅以下部分，了解如何配置和运行 SR-IOV 网络设备插件。

配置

配置参数

此插件根据与 SR-IOV 网络设备插件关联的配置映射（config map）中提供的配置创建设备插件端点。此文件的 JSON 格式如下所示：

{
"resourceList": [{
"resourceName": "intel_sriov_netdevice",
"selectors": [{
"vendors": ["8086"],
"devices": ["154c", "10ed", "1889"],
"drivers": ["i40evf", "ixgbevf", "iavf"]
}]
},
{
"resourceName": "intel_sriov_dpdk",
"resourcePrefix": "intel.com",
"selectors": [{
"vendors": ["8086"],
"devices": ["154c", "10ed", "1889"],
"drivers": ["vfio-pci"],
"pfNames": ["enp0s0f0","enp2s2f1"],
"needVhostNet": true
}]
},
{
"resourceName": "mlnx_sriov_rdma",
"resourcePrefix": "mellanox.com",
"selectors": [{
"vendors": ["15b3"],
"devices": ["1018"],
"drivers": ["mlx5_ib"],
"isRdma": true
}]
},
{
"resourceName": "infiniband_rdma_netdevs",
"selectors": [{
"linkTypes": ["infiniband"],
"isRdma": true
}]
},
{
"resourceName": "ct6dx_vdpa_vhost",
"selectors": [{
"vendors": ["15b3"],
"devices": ["101e"],
"drivers": ["mlx5_core"],
"vdpaType": "vhost"
}]
},
{
"resourceName": "intel_fpga",
"deviceType": "accelerator",
"selectors": [{
"vendors": ["8086"],
"devices": ["0d90"]
}]
},
{
"resourceName": "bf2_sf",
"resourcePrefix": "nvidia.com",
"deviceType": "auxNetDevice",
"selectors": [{
"vendors": ["15b3"],
"devices": ["a2d6"],
"pfNames": ["p0#1-5"],
"auxTypes": ["sf"]
}]
},
{
"resourceName": "intel_sriov_netdevice_additional_env",
"selectors": [{
"vendors": ["8086"],
"devices": ["154c", "10ed", "1889"],
"drivers": ["i40evf", "ixgbevf", "iavf"]
}],
"additionalInfo": {
"*": {
"token": "3e49019f-412f-4f02-824e-4cd195944205"
}
}
},
{
"resourceName": "brcm_sriov_bnxt",
"resourcePrefix": "broadcom.com",
"selectors": [{
"vendors": ["14e4"],
"devices": ["1750"],
"drivers": ["bnxt_en"]
}],
},
{
"resourceName": "old_selectors_syntax_example",
"selectors": {
"vendors": ["8086"],
"devices": ["154c", "10ed", "1889"],
"drivers": ["i40evf", "ixgbevf", "iavf"]
}
}
]
}

"resourceList" 应包含配置对象列表。每个配置对象可包含以下字段：

[!NOTE] "resourceName" 仅需在给定前缀（包括 CLI 参数中全局指定的前缀）范围内保持唯一，例如 "example.com/10G"、"acme.com/10G" 和 "acme.com/40G" 都是完全有效的名称。

设备选择器

"selectors" 字段既接受单个对象，也接受选择器对象列表。虽然两种格式均受支持，但建议使用列表语法。使用列表语法时，每个选择器对象将按列表中的顺序进行计算。例如，单个对象如下所示：

"selectors": {"vendors": ["8086"],"devices": ["154c"]}

列表语法如下所示：

"selectors": [{"vendors": ["8086"],"devices": ["154c"]}, {"vendors": ["8086"], "needVhostNet": true}]

列表语法示例在列表中指定了两个选择器对象。在此示例中，第一个选择器对象指定的所有设备的供应商 ID 为 8086 且设备 ID 为 154c。第二个选择器对象指定所有供应商 ID 为 8086 的设备。由于选择器对象按指定顺序处理，供应商 ID 为 8086 且设备 ID 为 154c 的设备将不会应用 needVhostNet: true。对比另一个类似的示例：

"selectors": [{"vendors": ["8086"], "needVhostNet": true}, {"vendors": ["8086"],"devices": ["154c"]}]

在后一个示例中，选择器对象的顺序已交换。由于第二个对象指定的所有设备也由第一个对象指定，这使得第二个选择器对象无效。

给定的选择器对象包含"selectors"。"deviceType" 值决定该设备支持哪些选择器。每个选择器将按照下面选择器表格中列出的顺序进行计算。

加速器设备选择器

当 "deviceType" 为 "accelerator" 时，这些选择器适用。

网络设备选择器

当 "deviceType" 为 "netDevice" 时，这些选择器适用（注意：这是默认值）

AdditionalInfo 字段

此字段定义了一种方法，可将信息添加到 sriov-network-device-plugin 注入容器的环境变量中。

示例：

"additionalInfo": {
"*": {
"token": "3e49019f-412f-4f02-824e-4cd195944205"
}
}

'*' 是一个特殊键，指示设备插件将此信息注入所有与选择器匹配的设备。如果要覆盖特定设备的信息或为其添加更多信息，也可以指定特定的 PCI 地址

"additionalInfo": {
"*": {
"token": "3e49019f-412f-4f02-824e-4cd195944205"
},
"0000:86:00.0": {
"additional-token": "6e7dc135-7a1c-456f-a008-c2cfb37997be"
}

}

分配不同 deviceID 的 Pod 的输出：
{"0000:3b:02.6":{"extraInfo":{"token":"3e49019f-412f-4f02-824e-4cd195944205"}

分配特定 deviceID 的 Pod 的输出：
{"0000:86:00.0":{"extraInfo":{"token":"3e49019f-412f-4f02-824e-4cd195944205","additional-token": "6e7dc135-7a1c-456f-a008-c2cfb37997be"}

当 '*' 和特定 deviceID 变量具有相同的键时，将采用特定的键

"additionalInfo": {
"*": {
"token": "original"
},
"0000:86:00.0": {
"token": "specific"
}

}

分配不同 deviceID 的 Pod 的输出：
{"0000:3b:02.6":{"extraInfo":{"token":"original"}

分配特定 deviceID 的 Pod 的输出：
{"0000:86:00.0":{"extraInfo":{"token":"specific"}

设备插件最初会发现主机中所有PCI网络资源并填充初始“设备列表”。如果设备类型是辅助网络设备（auxNetDevice），则对于每个发现的Netdevice类型PCI设备，插件会发现辅助设备。然后，每个“资源池”会按顺序将其选择器对象应用于发现的设备列表。插件会将满足选择器对象约束的设备添加到资源池中。选择器对象中指定的每个“选择器”都会缩小资源池的设备列表范围。当前，选择器按以下顺序应用：

1. “vendors” - 设备的供应商十六进制代码
2. “devices” - 设备的设备十六进制代码
3. “drivers” - 设备注册时使用的驱动程序名称
4. “pciAddresses” - 设备的PCI地址（BDF表示法，若设备类型为加速器或netDevice）
5. “acpiIndexes” - 设备的ACPI索引
6. “auxTypes” - 辅助网络设备的类型（若设备类型为auxNetDevice）
7. “pfNames” - 物理功能（PF）名称
8. “rootDevices” - 物理功能（PF）的PCI地址
9. “linkTypes” - 与PCI设备关联的网络设备的链路类型

如果单个设备匹配多个选择器对象，它将仅分配给第一个选择器对象。

“pfNames”和“rootDevices”选择器可用于按以下格式为资源池指定VF/SF的列表和/或范围：

" # , - , , , - "

或

CODE_TOKEN_13`

其中：

- 是PF接口名称 - 是PF PCI地址 - 是包含在池中的单个功能索引（从0开始） - 是范围中包含的第一个功能索引（从0开始） - 是范围中包含的最后一个功能索引（从0开始）

示例：

针对名称为netpf0的接口以及VF 0、2至7（包含2和7）和9的选择器如下所示：

"pfNames": ["netpf0#0,2-7,9"]

针对PCI地址0000:86:00.0以及VF 0、1、3、4的选择器如下所示：

CODE_TOKEN_15`

如果选择器中仅指定了PF网络接口或PF PCI地址，则默认该接口的所有VF或SF都将加入资源池。

部署连接到预创建 SR-IOV 网络的演示 Pod

首先，确保您的 Pod 从正确的设备池请求适当数量的设备：

[cloudadmin@controller-1 ~]$ grep -B1 sriov_ sriov_pod.yaml
requests:
nokia.k8s.io/sriov_ens2f1: '2'
limits:
nokia.k8s.io/sriov_ens2f1: '2'

然后实例化 Pod：

[cloudadmin@controller-1 ~]$ kubectl create -f sriov_pod.yaml
pod/sriov-pod created

验证演示 Pod 的状态和网络连接

[cloudadmin@controller-1 ~]$ kubectl get pod sriov-pod -n example-sriov
NAME        READY   STATUS    RESTARTS   AGE
sriov-pod   1/1     Running   0          111s

[cloudadmin@controller-1 ~]$ kubectl exec -n example-sriov -it sriov-pod -- ip addr show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
3: eth0@if49: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 8950 qdisc noqueue
    link/ether 8a:74:fd:e0:ee:fa brd ff:ff:ff:ff:ff:ff
    inet 10.244.3.8/24 brd 10.244.3.255 scope global eth0
       valid_lft forever preferred_lft forever
9: second_path2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq qlen 1000
    link/ether e2:19:e0:1b:91:44 brd ff:ff:ff:ff:ff:ff
26: first_path1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq qlen 1000
    link/ether 7e:0d:fa:eb:83:8c brd ff:ff:ff:ff:ff:ff

Pod 设备信息

已分配的设备信息通过容器的环境变量导出。变量名称为 PCIDEVICE_ 后接完整的扩展资源名称（例如 intel.com/sriov 等），扩展资源名称需大写，且所有特殊字符（“.”、“/”）替换为下划线（“_”）。如果从同一扩展资源池分配多个设备，设备 ID 之间用逗号（“,”）分隔。

例如，如果从 intel.com/sriov 扩展资源分配了 2 个设备，则已分配的设备信息将在以下环境变量中找到： PCIDEVICE_INTEL_COM_SRIOV=0000:03:02.1,0000:03:04.3

还有另一个环境变量以 JSON 格式公开已分配设备的更多信息，如挂载信息和请求的附加变量。该变量名称为 PCIDEVICE_ _INFO 后接完整的扩展资源名称（例如 intel.com/sriov 等），扩展资源名称需大写，且所有特殊字符（“.”、“/”）替换为下划线（“_”）。

vfio 设备示例：

PCIDEVICE_INTEL_COM_DPDK_NIC_1_INFO={"0000:3b:02.6":{"vfio":{"vfio-dev-mount":"/dev/vfio/169","vfio-mount":"/dev/vfio/vfio"},"vhost":{"net-mount":"/dev/vhost-net","tun-mount":"/dev/net/tun"}}}

# 在资源定义中添加 additionalInfo 字段将为每个已分配设备添加额外信息。例如：
PCIDEVICE_INTEL_COM_DPDK_NIC_1_INFO={"0000:3b:02.6":{"extraInfo":{"token":"3e49019f-412f-4f02-824e-4cd195944205"},"vfio":{"vfio-dev-mount":"/dev/vfio/169","vfio-mount":"/dev/vfio/vfio"},"vhost":{"net-mount":"/dev/vhost-net","tun-mount":"/dev/net/tun"}}}

虚拟部署支持

在虚拟环境中配置设备插件扩展选择器

SR-IOV 网络设备插件支持在虚拟化环境中运行。但是，并非所有设备选择器都适用，因为 VF 是透传给 VM 的，与它们各自的 PF 没有关联，因此任何依赖 VF 与其 PF 关联的设备选择器都无法工作，因此 pfNames 和 rootDevices 扩展选择器在虚拟部署中无法使用。通用选择器 pciAddress 可用于选择虚拟设备。

虚拟环境中的 CNI 插件

SR-IOV CNI 插件不支持在虚拟化环境中运行，因为它始终需要访问 PF 设备，而 PF 设备通常不存在于 VM 中。在虚拟化环境中推荐使用的 CNI 插件是 host-device CNI 插件。

无 IOMMU 的虚拟环境

SR-IOV 网络设备插件支持在没有虚拟化 IOMMU 的虚拟化环境中分配 VFIO 设备。有关更多信息，请参阅 此文档。

多架构支持

支持的架构：

• AMD64
• ARM64
• PPC64LE
• S390X

构建镜像：

$ DOCKERFILE=Dockerfile make image

容器设备接口

要启用容器设备接口（CDI）部署，请参见 CDI。

问题与贡献

我们欢迎您对本项目提供反馈和贡献。有关贡献指南，请参见 CONTRIBUTING.md。