CNI debug 插件实战指南：CNI 插件开发与排障的瑞士军刀

CNI debug 插件实战指南：CNI 插件开发与排障的瑞士军刀

发布时间：2026/10/10 8:45:29
CNI debug 插件实战指南：CNI 插件开发与排障的瑞士军刀 云原生网络后端【免费下载链接】cniContainer Network Interface - networking for Linux containers项目地址https://gitcode.com/gh_mirrors/cn/cni点击查看免费下载导读debug是 CNIContainer Network Interface仓库中专门为 CNI 插件开发、调试与排障设计的辅助插件。它可以在插件链plugin chain中记录每一个 CNI 操作请求的完整上下文容器 ID、网络命名空间、接口名、标准输入数据等并支持在容器网络命名空间内注入自定义排查命令hooks。读完本文你将掌握 debug 插件的全部配置参数、典型链式配置方法以及如何借助它快速定位插件开发中的问题。一、debug 插件是什么根据 plugins/debug/README.md 的定义该插件的目标非常明确帮助 CNI 插件开发过程中进行调试debugging与排障troubleshooting。它本身不负责创建网络而是作为插件链中的一个观察者和执行器观察者通过cniOutput把每一次 CNI 请求ADD/DEL/CHECK的完整参数落盘到文件供开发者事后分析执行器通过addHooks/delHooks/checkHooks在容器网络命名空间内执行自定义 shell 命令便于开发者在接口创建、删除、检查的关键节点注入排查逻辑。从源码结构看debug 插件是一个独立的 Go module见 plugins/debug/go.mod模块名为github.com/containernetworking/cni/plugins/debug通过replace指令指向仓库根目录的 CNI 库本身依赖github.com/containernetworking/cni v1.1.2与github.com/containernetworking/plugins v1.4.0。二、从源码看工作原理debug 插件的全部实现集中在 plugins/debug/main.go仅约 150 行核心逻辑非常清晰配置解析parseConf()将标准输入stdin中的 JSON 配置反序列化为NetConf结构体。结构体定义了插件的全部配置项对应 README 中的 Config Referencetype NetConf struct { types.NetConf CNIOutput string json:cniOutput,omitempty AddHooks [][]string json:addHooks,omitempty DelHooks [][]string json:delHooks,omitempty CheckHooks [][]string json:checkHooks,omitempty }注册三个生命周期操作main()调用skel.PluginMain(cmdAdd, cmdCheck, cmdDel, version.All, ...)即复用 CNI 的 skel 骨架库 完成环境变量解析、版本协商与 stdin 读取分别处理 ADD、CHECK、DEL 三种 CNI 命令。每个命令两条职责若配置了cniOutput以追加写入os.O_APPEND、权限0644的方式打开目标文件先写入CmdAdd/CmdCheck/CmdDel命令名再调用outputCmdArgs()落盘完整的请求参数若配置了对应 hooks调用executeHooks()进入容器网络命名空间执行命令。三、配置项详解Config ReferenceREADME 中共定义了 4 个配置项全部可选1.cniOutputstring可选指定一个文件路径插件会把 CNI 请求输出写入该文件。格式固定为命令名CmdAdd/CmdCheck/CmdDel ContainerID: 容器ID Netns: 网络命名空间路径 IfName: 接口名 Args: CNI_ARGS 扩展参数 Path: CNI_PATH 插件搜索路径 StdinData: 本次请求的完整 stdin JSON ----------------------从源码看outputCmdArgs()使用了fmt.Fprintf按固定模板输出见 plugins/debug/main.go其中StdinData是完整的原始 JSON 字符串。ADD 操作会额外输出prevResult前一插件的结果因为getResult()会解析RawPrevResult而 DEL/CHECK 操作返回空结果。这一特性对观察插件链数据流转特别有价值。2.addHooks命令数组可选接口 ADD 时在容器网络命名空间内执行的命令列表。示例中给出的写法为addHooks: [ [ sh, -c, ip link set $CNI_IFNAME promisc on ] ]注意虽然 README 描述为 string array但实际源码类型是[][]string命令 参数的嵌套数组第一个元素是命令名如sh、ip其余元素是该命令的参数。hooks 内可以直接引用 CNI 环境变量如$CNI_IFNAME接口名、$CNI_CONTAINERID容器 ID等。3.delHooks命令数组可选接口 DEL删除时在容器网络命名空间内执行的命令列表用途与addHooks对称常用于清理排查现场。4.checkHooks命令数组可选接口 CHECK 时在容器网络命名空间内执行的命令列表。CHECK 操作仅适用于 CNI 规范 v0.4.0 及更高版本可用来在运行时校验接口状态是否符合预期。四、完整配置示例与构建安装4.1 标准插件链配置conflistdebug 插件以链中一环的形式工作。README 给出了一个非常典型的场景ptp建网 debug排障 portmap端口映射。完整配置如下需保存为.conflist文件{ cniVersion: 0.3.1, name: mynet, plugins: [ { type: ptp, ipMasq: true, ipam: { type: host-local, subnet: 172.16.30.0/24, routes: [ { dst: 0.0.0.0/0 } ] } }, { type: debug, cniOutput: /tmp/cni_output.txt, addHooks: [ [ sh, -c, ip link set $CNI_IFNAME promisc on ] ] }, { type: portmap, capabilities: {portMappings: true}, externalSetMarkChain: KUBE-MARK-MASQ } ] }该配置的含义ptp 插件负责创建 veth 对并分配 IP172.16.30.0/24子网、默认路由debug 插件夹在中间把 ADD 请求完整记录到/tmp/cni_output.txt同时把eth0接口设置为混杂模式promiscportmap 插件最后处理端口映射依赖 K8s 的KUBE-MARK-MASQ标记链。由于 debug 插件的输入包含前一插件ptp的prevResult落盘日志能完整还原ptp 分配了哪些 IP/接口这一信息方便比对。4.2 构建与安装在仓库根目录执行Go 1.21go build -o debug ./plugins/debug # 或进入插件目录单独构建 cd plugins/debug go build -o debug .将生成的debug可执行文件放入CNI_PATH指向的目录如/opt/cni/bin即可被 cnitool 或容器运行时发现。4.3 用 cnitool 触发配合仓库自带的 cnitoolCNI 命令行工具即可手动复现完整插件链。cnitool 通过CNI_PATH查找插件通过NETCONFPATH默认/etc/cni/net.d读取配置*.conflist文件优先级高于*.confsudo ip netns add testing sudo CNI_PATH/opt/cni/bin cnitool add mynet /var/run/netns/testing cat /tmp/cni_output.txt # 查看 ADD 请求记录 sudo CNI_PATH/opt/cni/bin cnitool check mynet /var/run/netns/testing sudo CNI_PATH/opt/cni/bin cnitool del mynet /var/run/netns/testing sudo ip netns del testing其中cnitool add的底层调用是libcni的AddNetworkList()见 cnitool/cmd/add.go会按顺序执行 conflist 中的每个插件并把前序结果作为prevResult传入这正是 debug 插件能记录完整链式上下文的原因。五、Sample CNI Output 深度解读README 给出了两次真实请求的落盘样例下为 ADD 部分CmdAdd ContainerID: cnitool-20c433bb2b1d6ede56d6 Netns: /var/run/netns/cnitest IfName: eth0 Args: Path: /opt/cni/bin StdinData: {cniOutput:/tmp/cni_output.txt,cniVersion:0.3.1,name:test,prevResult:{cniVersion:0.3.1,interfaces:[{name:veth92e295cc,mac:56:22:7f:b7:5b:75},{name:eth0,mac:46:b3:f3:77:bf:21,sandbox:/var/run/netns/cnitest}],ips:[{version:4,interface:1,address:10.1.1.2/24,gateway:10.1.1.1}],dns:{nameservers:[10.64.255.25,8.8.8.8]}},type:none} ----------------------逐字段解读字段含义排查价值CmdAdd本次触发的 CNI 命令判断生命周期事件是否按预期发生ContainerID容器 ID来自CNI_CONTAINERID关联具体容器实例Netns容器网络命名空间路径来自CNI_NETNS确认命名空间是否正确、是否存在IfName容器内接口名来自CNI_IFNAME确认接口命名是否符合预期ArgsCNI_ARGS扩展参数K8s 中常含IgnoreUnknown1等排查参数传递问题Path插件搜索路径CNI_PATH确认是否加载了正确的插件二进制StdinData插件收到的完整 JSON 配置核心排查项包含prevResult全量数据StdinData中的prevResult是插件链调试的关键它展示了 ptp 插件返回的接口列表veth92e295cc与eth0、MAC 地址、IP 分配10.1.1.2/24网关10.1.1.1以及 DNS 配置。如果后续插件行为异常对照该数据即可判断是上游结果错误还是下游处理错误。DEL 记录则相对精简——StdinData中不再携带prevResult只有插件自身配置与type字段符合 CNI 规范中 DEL 请求的语义。六、Hooks 的执行细节与注意事项6.1 执行位置容器网络命名空间executeHooks()的实现见 plugins/debug/main.go揭示了 hooks 的运行机制通过ns.GetNS(netnsName)打开CNI_NETNS指向的命名空间调用netns.Do(...)将当前线程切换进该命名空间底层由pkg/ns封装Linux 实现见 pkg/ns/ns_linux.go在命名空间内依次exec.Command执行每个 hook命令与参数即[][]string配置中的元素。这意味着 hooks 里执行的ip link、ip addr等命令看到的都是容器内的网络环境可以直接操作$CNI_IFNAME对应的接口——这是该插件能在接口创建现场注入命令的根本原因。6.2 两个重要局限务必注意不捕获命令失败README 明确指出 just execute it and does not catch command failure。从源码看executeHooks()即使遇到exec.Command报错也只是把输出和错误打印到 stderr不向 CNI 运行时返回错误ADD/DEL 依然成功。因此 hooks 适合旁路排查不能用于强校验命名空间不可用时静默跳过若ns.GetNS失败例如 DEL 时命名空间已被删除函数直接返回不会中断流程。这在调试容器已销毁后的清理路径时需要注意。6.3 典型 hook 用法addHooks: [ [ sh, -c, ip link set $CNI_IFNAME promisc on ], [ ip, addr, show, $CNI_IFNAME ] ]第一条将接口置为混杂模式对抓包排查有意义第二条在命名空间内打印接口地址信息。也可以写日志文件addHooks: [ [ sh, -c, ip addr show $CNI_IFNAME /tmp/netns_eth0.txt 21 ] ]七、适用场景与最佳实践综合文档与源码debug 插件最适合以下场景CNI 插件链开发调试在自研插件前后插入 debug 插件通过cniOutput观察上下游数据尤其prevResult是否符合预期接口配置现场取证用addHooks/delHooks在命名空间内抓取接口状态、路由表作为问题定位的现场快照运行时状态校验辅助配合cnitool check仅 v0.4.0 规范观察 CHECK 路径的请求内容。实践中建议将cniOutput指向独立文件如/tmp/cni_output.txt借助追加写模式连续记录多次操作便于对比 ADD/DEL 的差异hooks 命令保持只读取证 轻量修改因为命令失败不会回滚也不影响 CNI 结果排查完毕后及时从 conflist 中移除 debug 插件避免生产环境产生额外 IO 与副作用。八、总结debug 插件用极简的设计一个结构体、三个回调、一个输出函数解决了 CNI 开发中最头痛的黑盒问题请求参数看不见、命名空间内状态摸不着。通过cniOutput记录请求全貌、通过三类 hooks 注入现场命令配合 cnitool 手动触发插件链开发者可以低成本地复现、观察和定位插件链中的绝大多数问题。其完整实现仅一个文件 plugins/debug/main.go非常适合作为学习 CNI 插件骨架skel、版本协商version.All与网络命名空间切换机制的入门范本。赞分享云原生网络后端【免费下载链接】cniContainer Network Interface - networking for Linux containers项目地址https://gitcode.com/gh_mirrors/cn/cni点击查看免费下载相关推荐oh-my-zsh 的 n98-magerun 插件Magento 开发者的命令行瑞士军刀oh my zsh 的 n98 magerun 插件Magento 开发者的命令行瑞士军刀 n98 magerun 是面向 Magento 开发者、系统管理员CLI开发工具插件系统上一篇如何在5分钟内为PotPlayer安装百度字幕翻译插件完整新手指南下一篇用 Cmd-Shift-C 一键进入检查模式Chrome DevTools 快速选中 DOM 元素的提速指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考