DOCA Flow Inspector 服务指南

本指南提供关于如何在 NVIDIA® BlueField® DPU 之上使用 DOCA Flow Inspector 服务容器的说明。

简介

DOCA Flow Inspector 服务支持实时数据监控和遥测组件的提取。这些组件可以被各种服务利用，包括那些专注于安全、大数据和其他用途的服务。

DOCA Flow Inspector 服务链接到 DOCA Telemetry Service (DTS)。它从用户接收镜像数据包，解析数据，并将其转发到 DTS，DTS 聚合来自各种提供商和来源的预定义统计信息。该服务利用 DOCA Telemetry Exporter API 与 DTS 通信，而 DPDK 基础设施促进了用户空间层的数据包采集。

DOCA Flow Inspector 在 BlueField 上其专用的 Kubernetes pod 中运行，旨在接收镜像数据包以进行分析。接收到的数据包被解析并以预定义的结构传输到遥测收集器，该收集器管理剩余的遥测方面。

flow-inspector-service-arch-version-1-modificationdate-1734472749677-api-v2.png

服务流程

DOCA Flow Inspector 接收 JSON 格式的配置文件，其中包含应过滤哪些镜像数据包以及应将哪些信息发送到 DTS 进行检查。

配置文件可以包含“export-units”属性下的多个导出单元。每个单元都包含“filter”和“export”。每个匹配一个过滤器（基于 L4 标头中的协议和端口）的数据包，然后被解析为导出中定义的相应请求结构。只有该信息被发送用于检查。不匹配任何过滤器的数据包将被丢弃。

此外，配置文件可能包含 FI 可选配置标志，请参阅配置部分中的 JSON 格式和示例。

该服务在运行时监视 JSON 配置文件的更改，以及重新配置服务的任何更改。

DOCA Flow Inspector 在 DPDK 之上运行以获取 L4。然后对数据包进行过滤，并使用其导出单元索引进行硬件标记。然后根据其导出单元和导出结构解析数据包，然后使用 IPC 转发到遥测收集器。

flow-of-service-graph-version-1-modificationdate-1734472749983-api-v2.png

配置阶段

JSON 文件用作输入，以配置导出单元（即，过滤器和相应的导出结构）。
过滤器使用 DOCA Flow 库转换为 SF（可扩展功能端口）上的硬件规则。
与遥测收集器的连接已初始化，所有导出结构都已注册到 DTS。

检查阶段

流量镜像到相关的 SF。
入口流量通过配置的 SF 接收。
非 L4 流量和不匹配任何过滤器的数据包将使用硬件规则丢弃。
匹配过滤器的数据包将标记其匹配的导出单元索引，并传递到 Arm 内核中的软件层。
数据包通过导出单元的索引解析为所需的结构。
遥测信息使用 IPC 转发到遥测代理。
镜像数据包被释放。
如果 JSON 文件已更改，请使用更新的文件运行配置阶段。

要求

在部署 flow inspector 容器之前，请确保满足以下先决条件

创建所需的文件和目录。应自动创建文件夹。确保 .json 文件位于文件夹内

复制
已复制！

            
            $ touch /opt/mellanox/doca/services/flow_inspector/bin/flow_inspector_cfg.json

验证 DTS 的配置文件夹是否存在。它们应该在部署 DTS 时自动创建。

复制
已复制！

            
            $ sudo mkdir -p /opt/mellanox/doca/services/telemetry/config
$ sudo mkdir -p /opt/mellanox/doca/services/telemetry/ipc_sockets
$ sudo mkdir -p /opt/mellanox/doca/services/telemetry/data

根据 DOCA Flow 的需要分配大页内存

复制
已复制！

            
            $ echo '1024' | sudo tee -a /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
$ sudo mkdir /mnt/huge
$ sudo mount -t hugetlbfs -o pagesize=2M nodev /mnt/huge

根据BlueField 可扩展功能用户指南部署可扩展功能，并使用 Open vSwitch 命令相应地镜像数据包。

例如

将数据包从 p0 镜像到 sf4

复制
已复制！

            
            $ ovs-vsctl add-br ovsbr1
$ ovs-vsctl add-port ovsbr1 p0
$ ovs-vsctl add-port ovsbr1 en3f0pf0sf4
$ ovs-vsctl -- --id=@p1 get port en3f0pf0sf4 \
            -- --id=@p2 get port p0 \
            -- --id=@m create mirror name=m0 select-dst-port=@p2 select-src-port=@p2 output-port=@p1 \
            -- set bridge ovsbr1 mirrors=@m

镜像来自 pf0hpf 或 p0 且通过 sf4 的数据包

复制
已复制！

            
            $ ovs-vsctl add-br ovsbr1
$ ovs-vsctl add-port ovsbr1 pf0hpf
$ ovs-vsctl add-port ovsbr1 p0
$ ovs-vsctl add-port ovsbr1 en3f0pf0sf4
$ ovs-vsctl -- --id=@p1 get port en3f0pf0sf4 \
            -- --id=@p2 get port pf0hpf \
            -- --id=@m create mirror name=m0 select-dst-port=@p2 select-src-port=@p2 output-port=@p1 \
            -- set bridge ovsbr1 mirrors=@m
$ ovs-vsctl -- --id=@p1 get port en3f0pf0sf4 \
            -- --id=@p2 get port p0 \
            -- --id=@m create mirror name=m0 select-dst-port=@p2 select-src-port=@p2 output-port=@p1 \
            -- set bridge ovsbr1 mirrors=@m

最后命令（创建镜像）的输出应输出类似于以下字母和数字序列

复制
已复制！

            
            0d248ca8-66af-427c-b600-af1e286056e1

注意

指定的 SF 必须创建为受信任功能。更多详细信息可以在BlueField 可扩展功能用户指南中找到。

服务部署

有关在 BlueField DPU 之上部署 DOCA 容器的信息，请参阅NVIDIA DOCA 容器部署指南。

DTS 在 NGC（NVIDIA 的容器目录）上可用。特定于服务的配置步骤和部署说明可以在服务的容器页面下找到。

注意

运行 DTS 和 DOCA Flow Inspector 的顺序很重要。您必须启动 DTS，等待几秒钟，然后启动 DOCA Flow Inspector。

配置

JSON 输入

DOCA Flow Inspector 配置文件应放置在 /opt/mellanox/doca/services/flow_inspector/bin/<json_file_name>.json 下，并以以下格式构建

复制
已复制！

            
            {
	/* Optional param, time period to check for changes in JSON config file (in seconds) and flush telemetry buffer if enabled (default is 60 seconds) */
	"config-sample-rate": <time>,
 
	/* Optional param, telemetry buffer size in bytes (default is 60KB) */
	"telemetry-buffer-size": <size>,
 
	/* Optional param, enable periodic telemetry buffer flush and defining the period time (in seconds) */  
	"telemetry-flush-rate": <numeric value in seconds>,
 
	/* Mandatory param, Flow Inspector export units */
	"export-units":
	[
 
		/* Export Unit 0 */
		{
			"filter":
			{     "protocols": [<L4 protocols separated by comma>], # What L4 protocols are allowed
			      "ports":
					[        
							[<source port>, <destination port>],
                    		[<source ports range>, <destination ports range>],
                    		<... more pairs of source, dest ports>
			        ]
			},
			"export":
			{
            		"fields": [<fields to be part of export struct, separated by comma>] # the Telemetry event will contain these fields.
 
			}
		},
        <... More Export Units> 
	]
}

导出单元属性

允许的协议

“TCP”
“UDP”

端口范围

可以为源端口和目标端口插入端口范围
范围应包括边界 [start_port-end_port]

允许的端口

范围 0-65535 中的所有端口，以字符串形式
或 * 表示任何端口

导出结构中允许的字段

timestamp – 时间戳，指示服务何时收到
host_ip – 运行服务的主机的 IP
src_mac – 源 MAC 地址
dst_mac – 目标 MAC 地址
src_ip – 源 IP
dst_ip – 目标 IP
protocol – L4 协议
src_port – 源端口
dst_port – 目标端口
flags – 附加标志（仅与 TCP 相关）
data_len – 数据负载长度
data_short – 数据的简短版本（负载切片到前 64 个字节）
data_medium – 数据的中等版本（负载切片到前 1500 个字节）
data_long – 数据的长版本（负载切片到前 9*1024 个字节）

JSON 示例

复制
已复制！

            
            {  
	/* Optional param, time period to check for changes in JSON config file (in seconds) and flush telemetry buffer if enabled (default is 60 seconds) */
  	"config-sample-rate": 30,
 
	/* Optional param, telemetry maximum buffer size in bytes */
	"telemetry-buffer-size": 70000,
 
	/* Optional param, enable periodic telemetry buffer flush and defining the period time (in seconds) */
	"telemetry-flush-rate": 1.5,
 
   /* Mandatory param, Flow Inspector export units */
	"export-units":
	[
 
		/* Export Unit 0 */
		{
			"filter":
			{
				"protocols": ["tcp", "udp"],
				"ports":
					[
						["*","433-460"],
						["20480","28341"],
						["28341","20480"],
						["68", "67"],
						["67", "68"]
					]
			},
			"export":
			{
				"fields": ["timestamp", "host_ip", "src_mac", "dst_mac", "src_ip", "dst_ip", "protocol", "src_port",
					"dst_port", "flags", "data_len", "data_long"]
			}
		},
 
		/* Export Unit 1 */
		{
			"filter":
			{
				"protocols": ["tcp"],
				"ports":
					[
						["5-10","422"],
						["80","80"]
					]
			},
			"export":
			{
				"fields": ["timestamp","dst_ip", "host_ip", "data_len", "flags", "data_medium"]
			}
		}
	]
}

注意

如果数据包标头包含任何过滤器中未指定的 L4 端口或 L4 协议，则它们将被过滤掉。

Yaml 文件

从 NGC 下载的 .yaml 文件可以根据您的需要轻松编辑。

复制
已复制！

            
            env:
  # Set according to the local setup
  - name: SF_NUM_1
    value: "2"   # Additional EAL flags, if needed
  - name: EAL_FLAGS
    value: ""   # Service-Specific command line arguments
  - name: SERVICE_ARGS
    value: "--policy /flow_inspector/flow_inspector_cfg.json -l 60"

SF_NUM_1 值可以根据 OVS 配置中使用的 SF 进行更改，并且可以使用BlueField 可扩展功能用户指南中的命令找到。
EAL_FLAGS 值必须根据运行容器时所需的 DPDK 标志进行更改。
SERVICE_ARGS 是服务接收的运行时参数
- -l、--log-level <value> – 设置程序的（数字）日志级别 <10=禁用，20=严重，30=错误，40=警告，50=信息，60=调试，70=跟踪>
- -p、--policy <json_path> – 设置容器内的 JSON 路径

验证输出

启用写入 DTS 中的数据允许调试 DOCA Flow Inspector 的有效性。

要允许 DTS 本地写入，请取消注释 /opt/mellanox/doca/services/telemetry/config/dts_config.ini 中的以下行

复制
已复制！

            
            #output=/data

注意

dts_config.ini 中的任何更改都需要重新启动 pod 才能应用新设置。

schema 文件夹包含 JSON 格式的元数据文件，这些文件允许读取包含实际数据的二进制文件。二进制文件根据以下示例中所示的命名约定写入

注意

需要安装 tree 运行时实用程序 (apt install tree)。

复制
已复制！

            
            $ tree /opt/mellanox/doca/services/telemetry/data/
/opt/mellanox/doca/services/telemetry/data/
├── {year}
│   └── {mmdd}
│        └── {hash}
│             ├── {source_id}
│             │   └── {source_tag}{timestamp}.bin
│             └── {another_source_id}
│                  └── {another_source_tag}{timestamp}.bin
└── schema
    └── schema_{MD5_digest}.json

当以下情况发生时，会出现新的二进制文件

服务启动
当二进制文件的最大寿命/大小限制达到时
当 JSON 文件更改并且创建新的遥测模式时
一小时过去

如果不存在 schema 或 data 文件夹，请参阅DOCA Telemetry Service Guide中的故障排除部分。

注意

source_id 通常设置为机器主机名。source_tag 是描述收集的计数器的行，通常设置为提供商的名称或用户计数器的名称。

可以使用以下命令从 DTS 容器内完成读取二进制数据

复制
已复制！

            
            crictl exec -it <Container-ID> /opt/mellanox/collectx/bin/clx_read -s /data/schema /data/path/to/datafile.bin

假设来自示例的匹配导出单元 1 的数据包已到达，则本地写入的数据应以以下格式显示

复制
已复制！

            
            {
    "timestamp": 1656427771076130,
    "host_ip": "10.237.69.238",
    "src_ip": "11.7.62.4",
    "dst_ip": "11.7.62.5",
    "data_len": 1152,
    "data_short": "Hello World"
}

复制
已复制！

            
            $ sudo crictl pods
POD ID              CREATED             STATE               NAME        							        NAMESPACE           ATTEMPT             RUNTIME
3162b71e67677  		4 seconds ago       Ready               doca-flow-inspector-my-dpu                      default             0                   (default)
 
$ sudo crictl images
IMAGE                              		  TAG                 IMAGE ID            SIZE
k8s.gcr.io/pause                   		  3.2                 2a060e2e7101d		  487kB
nvcr.io/nvidia/doca/doca_flow_inspector   1.1.0-doca2.0.2     2af1e539eb7ab       86.8MB
 
$ sudo crictl ps
CONTAINER           IMAGE               CREATED             STATE               NAME                     ATTEMPT             POD ID              POD

解决方案

在大多数情况下，容器确实启动了，但立即退出。可以使用以下命令检查这一点

复制
已复制！

            
            $ sudo crictl ps -a
CONTAINER           IMAGE               CREATED             STATE               NAME                     ATTEMPT             POD ID              POD
556bb78281e1d       2af1e539eb7ab       6 seconds ago       Exited              doca-flow-inspector      1                   3162b71e67677       doca-flow-inspector-my-dpu

如果容器失败（即，Exited 状态），建议检查 Flow Inspector 的主日志，位于 /var/log/doca/flow_inspector/flow_inspector_fi_dev.log。

此外，在终止后的短时间内，也可以使用容器的 ID 查看容器日志

复制
已复制！

            
            $ sudo crictl logs 556bb78281e1d
...
2023-10-04 11:42:55 - flow_inspector - FI     - ERROR    - JSON file was not found <config-file-path>.

Pod 未列出

错误

当将容器的 YAML 文件放置在 Kubelet 的输入文件夹中时，服务 pod 未列在 pod 列表中

复制
已复制！

            
            $ sudo crictl pods
POD ID              CREATED             STATE               NAME        							        NAMESPACE           ATTEMPT             RUNTIME

解决方案

在大多数情况下，pod 由于缺少请求的大页内存而未启动。可以使用以下命令验证这一点

复制
已复制！

            
            $ sudo journalctl -u kubelet -e. . . 
Oct 04 12:12:19 <my-dpu> kubelet[2442376]: I1004 12:12:19.905064 2442376 predicate.go:103] "Failed to admit pod, unexpected error while attempting to recover from admission failure" pod="default/doca-flow-inspector-<my-dpu>" err="preemption: error finding a set of pods to preempt: no set of running pods found to reclaim resources: [(res: hugepages-2Mi, q: 104563999874), ]"

本页内容

简介

服务流程

要求

服务部署

配置

JSON 输入

导出单元属性

Yaml 文件

验证输出

故障排除

Pod 标记为“就绪”且未列出容器

错误

解决方案

Pod 未列出

错误

解决方案