尧图网页设计 
Cilium IP Options 包追踪实战用 eBPF 监控任意 IP Option 元数据MonitorTraceIPOption 与 Hubble 过滤【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本指南基于 Cilium v1.19 及以后版本引入的IP Options 包追踪IP Options packet tracing能力完整演示如何通过 Helm 参数bpf.monitorTraceIPOption让 Cilium 从数据包中检测并提取任意 IP Option 数据并在 Cilium Monitor 与 Hubble 中可视化查看。读完本文你将掌握搭建开启该特性的 kind 集群、使用nping手工注入带 IP Option 的流量、以及用hubble observe --ip-trace-id精确过滤指定 Trace ID 的完整实战流程并深入理解底层 eBPF 解析器的实现原理与边界条件。本教程原文位于 Documentation/observability/hubble/ip-packet-tracing.rst配套示例清单为 examples/kubernetes-ip-options/ip-options-pods.yaml。特性背景与适用场景在生产集群中sidecar 代理或上游网络设备常常会把自定义的元数据如 Trace ID、Stream ID、租户标识以IPv4 IP Options的形式注入数据包。过去这类信息对 Cilium 是不可见的运维人员无法在数据路径上观测这些元数据。Cilium v1.19 之后通过将bpf.monitorTraceIPOption配置为具体的 IP Option 类型值Cilium 会在数据路径中检测携带该 Option 的数据包提取其中嵌入的 Trace ID支持 2、4、8 字节三种长度展示提取结果到 Cilium Monitor 和 Hubble 的流记录中。需要强调的是Cilium 只负责“观测”这类元数据不负责注入。确保应用、sidecar 或网络设备向流量中注入所需的 IP Options是你的责任。此外当前实现仅面向 IPv4 数据包IPv6 尚不支持见下文源码分析中的TRACE_ID_SKIP_IPV6。前置条件开始之前请确认本机已安装以下依赖kind用于创建本地 Kubernetes 集群helm用于安装配置 Ciliumdockerkind 节点运行时的容器引擎ciliumCLI管理与调试 CiliumhubbleCLI可选可用make hubble在仓库内构建用于观察过滤流量。集群搭建与特性启用1. 编写 kind 配置新建kind-config-ip-tracing.yaml内容如下。该配置创建 2 个节点1 个 control-plane、1 个 worker并禁用默认 CNI以便 Cilium 接管kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker networking: disableDefaultCNI: true2. 创建 kind 集群kind create cluster --configkind-config-ip-tracing.yaml3. 添加 Helm 仓库helm repo add cilium https://helm.cilium.io/4. 安装 Cilium 并开启 IP Option 监控安装命令的核心是--set bpf.monitorTraceIPOption136。该值指定 Cilium 要提取的 IP Option 类型号136十六进制0x88代表 Stream ID后面小节将用它生成追踪报文helm install cilium cilium/cilium --namespace kube-system \ --set hubble.enabledtrue \ --set hubble.relay.enabledtrue \ --set hubble.ui.enabledtrue \ --set bpf.monitorTraceIPOption136 kubectl -n kube-system wait --forconditionready pod -l k8s-appcilium --timeout300s安装完成后请等待 Cilium agent Pod 全部就绪kubectl rollout status或上面的wait命令均可。手动验证用 nping 注入带 IP Option 的流量为了验证特性我们手工向数据包中注入一个已知的 Trace ID然后观察 Cilium 能否正确提取。本例使用 4 字节的载荷来满足 Option 长度的严格限制。1. 部署 Client 与 Server Pod部署一个nginxserver 和一个netshootclient镜像内含nping工具。完整清单见 examples/kubernetes-ip-options/ip-options-pods.yamlapiVersion: apps/v1 kind: Deployment metadata: name: client labels: app: client spec: replicas: 1 selector: matchLabels: app: client template: metadata: labels: app: client spec: containers: - name: client image: nicolaka/netshoot command: - sleep args: - infinity --- apiVersion: apps/v1 kind: Deployment metadata: name: server labels: app: server spec: replicas: 1 selector: matchLabels: app: server template: metadata: labels: app: server spec: containers: - name: server image: nginx ports: - containerPort: 80应用并等待就绪kubectl apply -f examples/kubernetes-ip-options/ip-options-pods.yaml kubectl rollout status deployment client kubectl rollout status deployment server2. 从 Client 向 Server 发送带合法 IP Option 的流量# 1. 获取 server Pod 的 IP server_ip$(kubectl get pods -l appserver -o jsonpath{.items[0].status.podIP}) # 2. 使用 nping 发送带 Option 136 (0x88) 的 TCP 包 # 格式: \x88 (Type 136) \x04 (数据头部总长度) \x34\x21 (数据/ID) # 数据 0x3421 对应十进制 13345 # 注意: 载荷长度必须严格为 2、4 或 8 字节。此处总长度 4 表示 2 字节载荷 kubectl exec deployment/client -- nping --tcp -p 80 --ip-options \x88\x04\x34\x21 -c 3 ${server_ip}对 Option 编码稍作解释IPv4 的 IP Options 由 1 字节的 Type、1 字节的 Length 以及Length-2字节的数据组成。\x88\x04\x34\x21表示Type0x88即 136Length4头部 2 字节 2 字节数据数据为0x3421按十进制读作13345这就是稍后要过滤的 Trace ID。使用 Hubble 观察提取结果1. 构建并连接 Hubble在本仓库根目录下构建 hubble CLI并通过cilium hubble port-forward建立连接cd hubble make hubble cilium hubble port-forward 2. 按 Trace ID 过滤针对注入的 ID13345十六进制0x3421进行精确过滤./hubble observe -f --ip-trace-id 13345此时应能看到client与serverPod 之间携带该 ID 的流记录。Hubble 过滤器要求--ip-trace-id的值必须大于 00会被拒绝并且可以重复指定多个值做多 ID 过滤见 hubble/cmd/observe/flows_filter.go 及其测试 hubble/cmd/observe/flows_filter_test.go。源码级原理eBPF 如何解析 IP Options解析入口与支持的长度eBPF 侧的解析逻辑集中在 bpf/lib/ip_options.h。首先看它对“合法长度”的定义宏值含义OPT16_LEN4Type/Length 固定 2 字节 2 字节 Trace ID 数据OPT32_LEN6Type/Length 固定 2 字节 4 字节 Trace ID 数据OPT64_LEN10Type/Length 固定 2 字节 8 字节 Trace ID 数据MAX_IPV4_OPTS3最多解析的 IPv4 Option 数量eBPF 循环展开上限IHL_WITH_NO_OPTS5无任何 Option 时的最小 IHL20 字节头部也就是说Trace ID 的载荷只支持 2、4、8 字节三种长度文档中的 4 字节 Option 正是 2 字节载荷的合法形态。解析流程与错误码trace_id_from_ctx()首先校验以太网类型IPv6 返回TRACE_ID_SKIP_IPV6值为 -100当前不支持非 IPv4 返回TRACE_ID_NO_FAMILY随后调用trace_id_from_ip4()在 IHL 限定的范围内逐个 Option 遍历#pragma unroll(MAX_IPV4_OPTS)保证循环可展开遇到IPOPT_END停止、IPOPT_NOOP跳过匹配到配置的 Option 类型后再按长度读取 2/4/8 字节的网络序数据作为 Trace ID。解析结果通过以下返回值区分返回值含义TRACE_ID_NOT_FOUND(0)Option 解析正常但未找到 Trace IDTRACE_ID_ERROR(-1)解析过程发生未指明错误TRACE_ID_INVALID(-2)找到 Trace ID 但长度非法TRACE_ID_NO_FAMILY(-3)数据包不是 IPv4/IPv6 之外的其他族TRACE_ID_UNSUPPORTED_LENGTH_ERROR(-4)Option 长度不在 2/4/8 字节范围内TRACE_ID_SKIP_IPV6(-100)IPv6 数据包暂不支持监控通知与 Hubble 展示链路提取到的 Trace ID 会随数据路径的监控通知上送。在 pkg/monitor/datapath_trace.go 与 pkg/monitor/datapath_drop.go 中TraceNotify/DropNotify通知结构均带有IPTraceID uint64字段对齐名ip_trace_id并在 JSON 序列化时以IPTraceID/IpTraceID输出对应测试见 pkg/monitor/datapath_trace_test.go。Hubble 侧在 hubble/cmd/observe/flows.go 注册了--ip-trace-id过滤器配合 pkg/hubble 的流处理链路将监控通知转换为可查询的流记录。这意味着除了命令行你还可以在 Hubble UI 或任何接入 Hubble Relay 的消费端按 Trace ID 维度检索流量。小结与排查提示特性开关bpf.monitorTraceIPOption类型号1360x88Stream ID是文档给出的示例可替换为你环境中实际使用的 Option 类型号。长度限制Option 载荷只能是 2、4、8 字节注入方必须严格匹配否则解析会落入TRACE_ID_INVALID/TRACE_ID_UNSUPPORTED_LENGTH_ERROR。协议限制当前仅支持 IPv4IPv6 数据包会被显式跳过TRACE_ID_SKIP_IPV6。责任边界Cilium 只负责观测注入 IP Options 需由应用、sidecar 或网络设备完成。过滤方式hubble observe --ip-trace-id id要求 ID 大于 0可重复传参实现多 ID 过滤。如果hubble observe -f --ip-trace-id 13345长时间无输出请依次检查集群是否以bpf.monitorTraceIPOption136安装、流量是否确实携带 Option 136、以及nping的--ip-options编码是否严格符合 TypeLengthData 格式。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium IP Options 包追踪实战：用 eBPF 监控任意 IP Option 元数据（MonitorTraceIPOption 与 Hubble 过滤）
Cilium IP Options 包追踪实战用 eBPF 监控任意 IP Option 元数据MonitorTraceIPOption 与 Hubble 过滤【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读本指南基于 Cilium v1.19 及以后版本引入的IP Options 包追踪IP Options packet tracing能力完整演示如何通过 Helm 参数bpf.monitorTraceIPOption让 Cilium 从数据包中检测并提取任意 IP Option 数据并在 Cilium Monitor 与 Hubble 中可视化查看。读完本文你将掌握搭建开启该特性的 kind 集群、使用nping手工注入带 IP Option 的流量、以及用hubble observe --ip-trace-id精确过滤指定 Trace ID 的完整实战流程并深入理解底层 eBPF 解析器的实现原理与边界条件。本教程原文位于 Documentation/observability/hubble/ip-packet-tracing.rst配套示例清单为 examples/kubernetes-ip-options/ip-options-pods.yaml。特性背景与适用场景在生产集群中sidecar 代理或上游网络设备常常会把自定义的元数据如 Trace ID、Stream ID、租户标识以IPv4 IP Options的形式注入数据包。过去这类信息对 Cilium 是不可见的运维人员无法在数据路径上观测这些元数据。Cilium v1.19 之后通过将bpf.monitorTraceIPOption配置为具体的 IP Option 类型值Cilium 会在数据路径中检测携带该 Option 的数据包提取其中嵌入的 Trace ID支持 2、4、8 字节三种长度展示提取结果到 Cilium Monitor 和 Hubble 的流记录中。需要强调的是Cilium 只负责“观测”这类元数据不负责注入。确保应用、sidecar 或网络设备向流量中注入所需的 IP Options是你的责任。此外当前实现仅面向 IPv4 数据包IPv6 尚不支持见下文源码分析中的TRACE_ID_SKIP_IPV6。前置条件开始之前请确认本机已安装以下依赖kind用于创建本地 Kubernetes 集群helm用于安装配置 Ciliumdockerkind 节点运行时的容器引擎ciliumCLI管理与调试 CiliumhubbleCLI可选可用make hubble在仓库内构建用于观察过滤流量。集群搭建与特性启用1. 编写 kind 配置新建kind-config-ip-tracing.yaml内容如下。该配置创建 2 个节点1 个 control-plane、1 个 worker并禁用默认 CNI以便 Cilium 接管kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker networking: disableDefaultCNI: true2. 创建 kind 集群kind create cluster --configkind-config-ip-tracing.yaml3. 添加 Helm 仓库helm repo add cilium https://helm.cilium.io/4. 安装 Cilium 并开启 IP Option 监控安装命令的核心是--set bpf.monitorTraceIPOption136。该值指定 Cilium 要提取的 IP Option 类型号136十六进制0x88代表 Stream ID后面小节将用它生成追踪报文helm install cilium cilium/cilium --namespace kube-system \ --set hubble.enabledtrue \ --set hubble.relay.enabledtrue \ --set hubble.ui.enabledtrue \ --set bpf.monitorTraceIPOption136 kubectl -n kube-system wait --forconditionready pod -l k8s-appcilium --timeout300s安装完成后请等待 Cilium agent Pod 全部就绪kubectl rollout status或上面的wait命令均可。手动验证用 nping 注入带 IP Option 的流量为了验证特性我们手工向数据包中注入一个已知的 Trace ID然后观察 Cilium 能否正确提取。本例使用 4 字节的载荷来满足 Option 长度的严格限制。1. 部署 Client 与 Server Pod部署一个nginxserver 和一个netshootclient镜像内含nping工具。完整清单见 examples/kubernetes-ip-options/ip-options-pods.yamlapiVersion: apps/v1 kind: Deployment metadata: name: client labels: app: client spec: replicas: 1 selector: matchLabels: app: client template: metadata: labels: app: client spec: containers: - name: client image: nicolaka/netshoot command: - sleep args: - infinity --- apiVersion: apps/v1 kind: Deployment metadata: name: server labels: app: server spec: replicas: 1 selector: matchLabels: app: server template: metadata: labels: app: server spec: containers: - name: server image: nginx ports: - containerPort: 80应用并等待就绪kubectl apply -f examples/kubernetes-ip-options/ip-options-pods.yaml kubectl rollout status deployment client kubectl rollout status deployment server2. 从 Client 向 Server 发送带合法 IP Option 的流量# 1. 获取 server Pod 的 IP server_ip$(kubectl get pods -l appserver -o jsonpath{.items[0].status.podIP}) # 2. 使用 nping 发送带 Option 136 (0x88) 的 TCP 包 # 格式: \x88 (Type 136) \x04 (数据头部总长度) \x34\x21 (数据/ID) # 数据 0x3421 对应十进制 13345 # 注意: 载荷长度必须严格为 2、4 或 8 字节。此处总长度 4 表示 2 字节载荷 kubectl exec deployment/client -- nping --tcp -p 80 --ip-options \x88\x04\x34\x21 -c 3 ${server_ip}对 Option 编码稍作解释IPv4 的 IP Options 由 1 字节的 Type、1 字节的 Length 以及Length-2字节的数据组成。\x88\x04\x34\x21表示Type0x88即 136Length4头部 2 字节 2 字节数据数据为0x3421按十进制读作13345这就是稍后要过滤的 Trace ID。使用 Hubble 观察提取结果1. 构建并连接 Hubble在本仓库根目录下构建 hubble CLI并通过cilium hubble port-forward建立连接cd hubble make hubble cilium hubble port-forward 2. 按 Trace ID 过滤针对注入的 ID13345十六进制0x3421进行精确过滤./hubble observe -f --ip-trace-id 13345此时应能看到client与serverPod 之间携带该 ID 的流记录。Hubble 过滤器要求--ip-trace-id的值必须大于 00会被拒绝并且可以重复指定多个值做多 ID 过滤见 hubble/cmd/observe/flows_filter.go 及其测试 hubble/cmd/observe/flows_filter_test.go。源码级原理eBPF 如何解析 IP Options解析入口与支持的长度eBPF 侧的解析逻辑集中在 bpf/lib/ip_options.h。首先看它对“合法长度”的定义宏值含义OPT16_LEN4Type/Length 固定 2 字节 2 字节 Trace ID 数据OPT32_LEN6Type/Length 固定 2 字节 4 字节 Trace ID 数据OPT64_LEN10Type/Length 固定 2 字节 8 字节 Trace ID 数据MAX_IPV4_OPTS3最多解析的 IPv4 Option 数量eBPF 循环展开上限IHL_WITH_NO_OPTS5无任何 Option 时的最小 IHL20 字节头部也就是说Trace ID 的载荷只支持 2、4、8 字节三种长度文档中的 4 字节 Option 正是 2 字节载荷的合法形态。解析流程与错误码trace_id_from_ctx()首先校验以太网类型IPv6 返回TRACE_ID_SKIP_IPV6值为 -100当前不支持非 IPv4 返回TRACE_ID_NO_FAMILY随后调用trace_id_from_ip4()在 IHL 限定的范围内逐个 Option 遍历#pragma unroll(MAX_IPV4_OPTS)保证循环可展开遇到IPOPT_END停止、IPOPT_NOOP跳过匹配到配置的 Option 类型后再按长度读取 2/4/8 字节的网络序数据作为 Trace ID。解析结果通过以下返回值区分返回值含义TRACE_ID_NOT_FOUND(0)Option 解析正常但未找到 Trace IDTRACE_ID_ERROR(-1)解析过程发生未指明错误TRACE_ID_INVALID(-2)找到 Trace ID 但长度非法TRACE_ID_NO_FAMILY(-3)数据包不是 IPv4/IPv6 之外的其他族TRACE_ID_UNSUPPORTED_LENGTH_ERROR(-4)Option 长度不在 2/4/8 字节范围内TRACE_ID_SKIP_IPV6(-100)IPv6 数据包暂不支持监控通知与 Hubble 展示链路提取到的 Trace ID 会随数据路径的监控通知上送。在 pkg/monitor/datapath_trace.go 与 pkg/monitor/datapath_drop.go 中TraceNotify/DropNotify通知结构均带有IPTraceID uint64字段对齐名ip_trace_id并在 JSON 序列化时以IPTraceID/IpTraceID输出对应测试见 pkg/monitor/datapath_trace_test.go。Hubble 侧在 hubble/cmd/observe/flows.go 注册了--ip-trace-id过滤器配合 pkg/hubble 的流处理链路将监控通知转换为可查询的流记录。这意味着除了命令行你还可以在 Hubble UI 或任何接入 Hubble Relay 的消费端按 Trace ID 维度检索流量。小结与排查提示特性开关bpf.monitorTraceIPOption类型号1360x88Stream ID是文档给出的示例可替换为你环境中实际使用的 Option 类型号。长度限制Option 载荷只能是 2、4、8 字节注入方必须严格匹配否则解析会落入TRACE_ID_INVALID/TRACE_ID_UNSUPPORTED_LENGTH_ERROR。协议限制当前仅支持 IPv4IPv6 数据包会被显式跳过TRACE_ID_SKIP_IPV6。责任边界Cilium 只负责观测注入 IP Options 需由应用、sidecar 或网络设备完成。过滤方式hubble observe --ip-trace-id id要求 ID 大于 0可重复传参实现多 ID 过滤。如果hubble observe -f --ip-trace-id 13345长时间无输出请依次检查集群是否以bpf.monitorTraceIPOption136安装、流量是否确实携带 Option 136、以及nping的--ip-options编码是否严格符合 TypeLengthData 格式。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考