Kubernetes CNI 网络插件实现原理：PodSandbox 与网络命名空间隔离

概述

本文档基于 Kubernetes mini-cni 项目的源代码注释编写，深入解析 CNI（Container Network Interface）插件的工作机制、PodSandbox 的生命周期管理以及容器网络的底层实现细节。

第一部分：RunPodSandbox 的核心职责

PodSandbox 的定义

RunPodSandbox 负责创建一个 Pod 的沙箱，也就是 Pause 容器加上 Network Namespace 的组合体。这是 Pod 网络初始化的绝对起点。

配置生成阶段

PodSandboxConfig 的结构

配置中需要填写的关键信息包括：

• Pod 的名字
• Namespace
• DNS 配置

这些信息会被打包成一个标准的 PodSandboxConfig 对象，传递给后续的 CRI 接口。

CRI 接口的调用链

runtimeService 的角色

m.runtimeService 就是 Containerd/Docker 的 CRI 客户端。通过这个客户端，Kubelet 可以与底层的容器运行时进行标准化的通信。

关键转折点

这一步之后，Containerd 会去调用 CNI 插件！

这是一个至关重要的转折：RunPodSandbox 本身并不直接配置网络，而是通过创建 Sandbox 触发 Containerd 调用 CNI 插件来完成网络配置。

第二部分：CNI 插件的二进制调用机制

调用位置的源码追溯

CNI 插件的调用逻辑位于 github.com/containernetworking/cni/pkg/invoke/raw_exec.go。这是一个独立的库，被所有符合 CNI 规范的容器运行时所使用。

四步调用流程

第一步：准备命令路径

直接调用二进制文件的路径。例如 /opt/cni/bin/mini-cni。这个路径通常在 Kubelet 启动时通过 --cni-bin-dir 参数指定。

第二步：准备标准输入

把 JSON 配置通过 Stdin（标准输入）塞进去。这就是为什么我们在 main.go 里要用 json.Unmarshal(os.Stdin) 来接收配置的原因。

这个 JSON 配置包含了：

• CNI 版本号
• 网络名称
• 具体的插件配置参数

第三步：设置环境变量

CNI 规范定义了一组标准的环境变量，必须在调用前设置好：

• CNI_COMMAND：操作类型，如 “ADD”、”DEL”、”CHECK”
• CNI_CONTAINERID：容器的唯一标识符
• CNI_NETNS：网络命名空间的路径
• CNI_IFNAME：接口名称（通常是 eth0）
• CNI_PATH：CNI 插件目录

这些环境变量是 CNI 插件获取上下文信息的官方渠道。

第四步：执行并返回结果

执行完毕后，CNI 插件需要通过 stdout 返回一个 Result JSON。这就是 Kubelet（通过 Containerd）收到的那个 Result JSON，包含了分配的 IP 地址、网关、路由等信息。

第三部分：CNI 插件的网络配置实战

Panic 捕获的工程实践

在插件入口处新增 Panic 捕获，防止程序崩溃了没有任何日志。这对于调试生产环境的网络问题至关重要。

Loopback 接口的启动

修复动作 1：启动 Loopback (lo) 接口。如果不启动这个，很多网络操作会莫名其妙失败。

lo 接口是每个网络命名空间的必备基础设施，它提供了本地回环通信的能力（127.0.0.1）。缺少 lo 接口会导致：

• 应用无法访问本地的健康检查端点
• gRPC/HTTP 客户端连接 localhost 失败
• 某些依赖本地 IPC 的中间件异常

因此，在任何网络配置开始前，必须先启用 lo 接口。

Veth Pair 的创建与配置

暴力清理策略

在创建新的 veth pair 之前，先进行暴力清理，清除可能残留的旧接口。这是一种防御性编程的实践，可以避免因接口重名导致的冲突。

Veth Pair 的本质

Veth Pair 是一对虚拟以太网设备，它们的特点是：从一个设备进入的数据包会从另一个设备出来，就像一根虚拟的网线连接了两个网口。

在 CNI 场景中：

• 一端放在容器的网络命名空间中（通常命名为 eth0）
• 另一端连接到宿主机的网桥上（通常带有随机后缀）

这样就建立了容器到宿主机网络的桥梁。

IP 地址的配置

为容器的 eth0 接口分配 IP 地址。这个 IP 通常是 Pod CIDR 范围内的一个空闲地址。

确保 eth0 处于 UP 状态

修复动作 2：显式确保 eth0 是 UP 的。虽然 SetupVeth 函数可能会做这件事，但再做一次是为了保险起见。

网络接口必须处于 UP 状态才能收发数据包。在某些边缘情况下（如内核版本差异、竞态条件），仅靠 SetupVeth 可能不足以保证接口激活，因此需要显式地再调用一次 netlink.LinkSetUp。

路由表的配置

默认网关的设置

配置一条默认路由，将所有非本地流量指向网关。这是容器能够访问外部网络的前提。

这里曾经是容易报错的地方，常见的问题包括：

• 网关 IP 不在同一子网
• 路由表已满
• 权限不足（需要 CAP_NET_ADMIN）

插入网桥

将 veth 的另一端插入到宿主机的网桥（如 cbr0 或 br-cni）上。这样做的目的是：

• 让容器能够通过二层交换机的方式与其他容器通信
• 让容器能够通过网桥的上联口访问外部网络

返回 Result JSON

最后一步是构造并返回 Result JSON，告知调用者（Containerd/Kubelet）网络配置的结果。标准的 Result 包含：

• 分配的 IP 地址和掩码
• 网关地址
• 路由表项
• DNS 配置（可选）

第四部分：CNI 插件命名的工程考量

名字的传递需求

CNI 插件的名称需要被传递和使用，因此在代码结构中定义为外部可见的常量或变量，而不是隐藏在内部作用域中。

这种设计的好处是：

• 便于日志记录和监控指标打点
• 方便在多插件串联的场景中进行区分
• 有利于错误诊断时的快速定位

总结：CNI 网络插件的设计哲学

通过分析 mini-cni 项目的源码注释，我们可以看到 Kubernetes 容器网络实现的几个核心原则：

分阶段初始化

Pod 网络的初始化不是一蹴而就的，而是分为清晰的两个阶段：

1. RunPodSandbox 阶段：创建 Pause 容器和网络命名空间
2. CNI 插件调用阶段：在具体命名空间中配置网络设备

这种分工的优势在于解耦：Kubelet 只需要关心 Pod 的生命周期，而不需要了解具体的网络技术细节；网络配置的复杂性被封装在了 CNI 插件中。

标准化接口的重要性

CNI 规范定义了严格的输入输出契约：

• 输入：JSON 配置 + 环境变量
• 输出：Result JSON
• 副作用：修改目标网络命名空间的网络配置

正是这种标准化，使得 Kubernetes 可以无缝对接数十种不同的 CNI 实现（Flannel、Calico、Cilium、Weave 等），而无需修改一行核心代码。

防御性编程的价值

从 Panic 捕获到双重确认接口 UP 状态，再到暴力清理残留资源，这些看似冗余的代码实际上都是生产环境血泪教训的结晶。在网络这种容易出现竞态条件和边缘场景的领域，防御性编程不是可选项，而是必选项。

可观测性的前置考虑

即使是像 CNI 插件这样短命的进程（生命周期可能只有几毫秒），也需要考虑日志记录和错误追踪。这也是为什么要在最开始就设置 Panic 捕获的原因——宁可牺牲一点点性能，也要保证出现问题时有迹可循。

理解 CNI 插件的工作原理，对于排查 Kubernetes 网络问题、开发自定义网络插件以及优化大规模集群的网络性能都具有重要的指导意义。

第五部分：CNI网络配置的实验验证

实验环境准备

为了验证CNI插件的实际工作效果，我们需要在一个干净的Linux环境中进行以下实验。实验目标是手动调用CNI插件，观察网络命名空间的创建和配置过程。

前置条件检查

确保系统中已安装以下组件：

1
2
3
4
5
6
7
8

# 检查CNI插件目录
ls -la /opt/cni/bin/

# 检查网桥模块是否加载
lsmod | grep bridge

# 检查CNI配置文件目录
ls -la /etc/cni/net.d/

实验一：手动创建网络命名空间

这个实验演示如何在没有Kubernetes的情况下，手动模拟PodSandbox的创建过程。

步骤1：创建网络命名空间

1
2
3
4
5
6
7
8

# 创建一个新的网络命名空间
sudo ip netns add test-pod-ns

# 验证命名空间已创建
ip netns list

# 进入命名空间执行命令
sudo ip netns exec test-pod-ns ip addr

预期输出应该显示除了lo接口外没有其他网络接口，这证明我们有了一个干净的网络环境。

步骤2：准备CNI配置文件

创建CNI插件的输入配置文件/tmp/cni-config.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "cniVersion": "1.0.0",
  "name": "mynet",
  "type": "mini-cni",
  "bridge": "cbr0",
  "isDefaultGateway": true,
  "ipam": {
    "type": "host-local",
    "subnet": "10.244.0.0/16",
    "routes": [
      { "dst": "0.0.0.0/0" }
    ]
  }
}

步骤3：设置CNI环境变量

CNI插件依赖一组标准环境变量来获取上下文信息：

1
2
3
4
5

export CNI_COMMAND=ADD
export CNI_CONTAINERID=test123
export CNI_NETNS=/var/run/netns/test-pod-ns
export CNI_IFNAME=eth0
export CNI_PATH=/opt/cni/bin

注意：CNI_NETNS必须是绝对路径。如果使用ip netns创建的命名空间，需要先绑定挂载：

1
2
3
4
5
6

# 创建绑定挂载点
sudo mkdir -p /var/run/netns
sudo ln -s /var/run/netns/test-pod-ns /var/run/netns/test-pod-ns

# 或者直接使用proc路径
export CNI_NETNS=/proc/$(pidof pause)/ns/net

步骤4：调用CNI插件

1
2

# 调用CNI插件并捕获输出
cat /tmp/cni-config.json | sudo /opt/cni/bin/mini-cni | jq .

预期的Result JSON输出应该包含：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "cniVersion": "1.0.0",
  "ips": [
    {
      "address": "10.244.1.2/16",
      "gateway": "10.244.0.1"
    }
  ],
  "routes": [
    {
      "dst": "0.0.0.0/0",
      "gw": "10.244.0.1"
    }
  ],
  "dns": {}
}

步骤5：验证网络配置

1
2
3
4
5
6
7
8

# 检查命名空间内的接口
sudo ip netns exec test-pod-ns ip addr show eth0

# 检查路由表
sudo ip netns exec test-pod-ns ip route

# 检查连通性（需要宿主机网桥已配置）
sudo ip netns exec test-pod-ns ping -c 3 10.244.0.1

实验二：观察Veth Pair的连接

这个实验演示容器与宿主机之间的网络连接是如何建立的。

步骤1：查看宿主机侧的veth接口

1
2
3
4
5

# 列出所有网络接口
ip link show

# 找到类似vethxxxx的接口（xxxx是随机字符串）
ip link show | grep veth

步骤2：查看网桥成员

1
2
3
4
5

# 安装网桥工具（如果未安装）
sudo apt-get install bridge-utils

# 查看网桥及其端口
brctl show cbr0

输出示例：

1
2
3

bridge name     bridge id               STP enabled     interfaces
cbr0            8000.0242ac110002       no              veth123abc
                                                        veth456def

这证明了多个容器的veth对端都已正确插入到同一个网桥中，形成了二层交换网络。

实验三：清理和删除操作

CNI插件不仅负责创建网络，还需要正确处理删除操作。

步骤1：发送DELETE命令

1
2

export CNI_COMMAND=DEL
cat /tmp/cni-config.json | sudo /opt/cni/bin/mini-cni

注意：DELETE命令通常不产生输出（成功的删除是静默的）。

步骤2：验证清理效果

1
2
3
4
5
6
7
8

# 检查命名空间是否还存在
ip netns list | grep test-pod-ns

# 检查veth接口是否已被移除
ip link show | grep veth

# 检查网桥端口
brctl show cbr0

实验四：模拟真实Pod场景

这个实验尽可能接近Kubernetes中Pod网络的实际创建流程。

步骤1：启动Pause容器

1
2

# 使用crictl或docker启动pause容器
sudo crictl runp sandbox-config.json

其中sandbox-config.json包含：

1
2
3
4
5
6
7
8
9
10

{
  "metadata": {
    "name": "test-pod",
    "namespace": "default",
    "uid": "test-uid-123"
  },
  "linux": {
    "cgroup_parent": "/kubepods/besteffort/podtest-uid-123"
  }
}

步骤2：获取容器PID和网络命名空间路径

1
2
3
4
5
6
7

# 获取pause容器的PID
PAUSE_PID=$(crictl inspect $(crictl pods --name test-pod -q) | jq .info.pid)

# 网络命名空间路径
NETNS_PATH="/proc/${PAUSE_PID}/ns/net"

echo "Network namespace: ${NETNS_PATH}"

步骤3：调用CNI插件配置网络

1
2
3
4
5
6
7

export CNI_COMMAND=ADD
export CNI_CONTAINERID=$(crictl pods --name test-pod -q)
export CNI_NETNS=${NETNS_PATH}
export CNI_IFNAME=eth0
export CNI_PATH=/opt/cni/bin

cat /etc/cni/net.d/10-mynet.conflist | sudo /opt/cni/bin/mini-cni

步骤4：验证Pod内网络

1
2
3
4

# 在容器内执行网络命令
crictl exec $(crictl ps -q) ip addr show eth0
crictl exec $(crictl ps -q) ip route
crictl exec $(crictl ps -q) cat /etc/resolv.conf

常见问题排查

问题1：权限拒绝错误

症状：调用CNI插件时报operation not permitted

原因：缺少CAP_NET_ADMIN能力

解决方案：

1
2
3
4
5

# 使用sudo或以root身份运行
sudo /opt/cni/bin/mini-cni

# 或者给二进制文件添加capability（不推荐用于生产）
sudo setcap cap_net_admin+ep /opt/cni/bin/mini-cni

问题2：网桥不存在

症状：failed to find bridge cbr0

原因：宿主机上没有创建指定的网桥

解决方案：

1
2
3
4
5
6

# 手动创建网桥
sudo ip link add name cbr0 type bridge
sudo ip link set cbr0 up

# 或者重启kubelet让它自动创建（取决于CNI配置）
sudo systemctl restart kubelet

问题3：IP地址耗尽

症状：failed to allocate IP range

原因：IPAM配置的子网太小，可用IP已分配完

解决方案：

1
2
3
4
5

# 检查已分配的IP
ls -la /var/lib/cni/networks/mynet/

# 扩大子网范围或清理旧的分配记录
rm /var/lib/cni/networks/mynet/last_reserved_ip

实验总结

通过这些实验，我们可以直观地观察到：

1. 网络命名空间的隔离效果：每个Pod都有独立的网络栈
2. Veth Pair的桥梁作用：连接容器内部与宿主机网络
3. CNI协议的简洁性：仅需JSON输入和环境变量即可完成复杂配置
4. 清理操作的重要性：避免资源泄漏需要显式的DELETE处理

这些动手实验不仅能加深对理论知识的理解，还能培养在实际生产环境中诊断和解决网络问题的能力。建议读者在自己的测试环境中完整复现以上实验，并尝试修改参数观察不同配置的效果。