Golang实现K8s自定义CNI插件教程

本文深入浅出地讲解了使用 Go 语言开发 Kubernetes 自定义 CNI 插件的核心要点：从必须严格实现 ADD/DEL 命令以满足 kubelet 的轻量级调用机制，到通过 veth pair、网络命名空间切换和精确路由配置打通容器网络的三大关键步骤；同时直击开发痛点——如避免 os.Args 硬编码而改用 CNI_COMMAND 环境变量、警惕 JSON 字段大小写与序列化方式、防范 stdin 读取截断、严守 netlink 操作错误处理，并提供基于命令行手动调试的高效排错路径，帮你避开 CPU 暴涨、Pod 卡死、IP 残留等典型陷阱，真正实现稳定、可调试、符合规范的 CNI 插件落地。

为什么 CNI 插件必须实现 ADD 和 DEL 两个命令？

因为 kubelet 不会调用你的插件“启动服务”，它只在 Pod 创建/销毁时，通过标准输入传入 JSON 配置，并期望你用 exit code + stdout 响应——ADD 成功返回 0 并输出 IP 分配结果，DEL 成功也返回 0，失败则返回非 0。没实现这两个，kubelet 就卡在 “ContainerCreating”。

• ADD 必须返回 {"ip4": {"ip": "10.244.1.10/24", "gateway": "10.244.1.1"}} 这类结构，否则 kubelet 解析失败，报 failed to parse CNI result
• DEL 虽然不强制要求做清理，但若跳过（比如直接 exit 0），宿主机上 veth peer、IP 地址、iptables 规则都会残留，几小时后 ip link 里堆满 vethxxxx，网络不通
• Golang 里别用 os.Args[1] 硬判断命令名，CNI 规范允许通过环境变量 CNI_COMMAND 读取，更可靠

怎么让容器网络真正走通：veth pair + namespace + 路由三步缺一不可

光配好 IP 不行，容器 netns 是隔离的，宿主机看不到容器内网卡，容器也看不到宿主机路由。必须手动把 veth 一端塞进容器 netns，另一端配 IP 并加路由。

• 创建 veth pair 后，用 syscall.Setns 切到容器 netns（需先 os.Open("/proc/[pid]/ns/net")），再用 netlink.LinkSetNsFd 把 veth peer 移入——Golang 标准库不支持，得用 github.com/vishvananda/netlink
• 宿主机侧 veth 接口要配 gateway IP（如 10.244.1.1），并开启 sysctl -w net.ipv4.ip_forward=1，否则流量出不去
• 容器内默认路由必须设为宿主机侧 veth IP：ip route add default via 10.244.1.1 dev eth0；漏掉这句，ping 8.8.8.8 会卡在 “no route to host”

plugin.go 里最容易被忽略的错误处理点

不是 panic 或 log.Fatal 就算处理了——CNI 插件崩溃或没输出，kubelet 会等 30 秒超时，然后重试，反复拉起进程，CPU 占满，日志刷屏。

• 所有 netlink 操作必须检查 error，比如 netlink.LinkAdd 失败时可能因设备名已存在，要先 LinkByName 查重，不能直接覆盖
• 读取 stdin 的 JSON 必须用 io.ReadAll(os.Stdin)，别用 bufio.Scanner（默认 64KB 缓冲，CNI 配置超长时截断，解析失败）
• 写 stdout 用 json.NewEncoder(os.Stdout).Encode(result)，别手拼字符串——字段名大小写、空格、换行都影响 kubelet 解析，常见错是返回 {ip4: {...}}（小写 ip4）而非规范要求的 ip4

调试时怎么快速定位是插件问题还是 CNI 配置问题？

别一上来就改 Go 代码。先用 cni-plugin 命令行模式复现，绕过 kubelet 干扰。

• 手动构造 JSON 输入：echo '{"cniVersion":"1.0.0","name":"mynet","type":"mycni","ipMasq":true,"ipam":{"type":"host-local","subnet":"10.244.1.0/24"}}' | sudo ./mycni ADD /var/run/mycontainer/netns
• 检查输出是否含 "ip4" 字段且 exit code 为 0；失败时看 stderr，常见是 failed to open netns "/var/run/..."（路径错或权限不足）或 link already exists（上次 DEL 没清理）
• 对比 /etc/cni/net.d/10-mynet.conflist 里的 type 字段和插件文件名是否一致，不一致会导致 kubelet 找不到二进制，报 no valid plugins found

网络包转发本身不难，难的是每一步都在不同 namespace、不同权限上下文里执行，少一个 Setns、漏一条 ip route、错一个 JSON key，整条链就断了。调试时盯着 ip link 和 ip netns exec 看实时变化，比读日志快得多。

好了，本文到此结束，带大家了解了《Golang实现K8s自定义CNI插件教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！