CNI学习笔记

Kubernetes没有提供默认可用的容器网络，第三方提供的容器网络，必须满足以下条件：

1. 容器之间可以相互通信，且不需要NAT
2. 宿主机和容器可以相互通信，且不需要NAT
3. 容器看到自己的IP，和其它节点/容器看到的它的IP，是一样的

即集群包含的每一个容器都拥有一个与集群中其它的容器、节点可直接路由的独立IP地址。但是Kubernetes并没有具体实现这样一个网络模型，而是设计了一个开放的容器网络标准CNI。

K8S容器网络，具有两种实现风格：

1. Overlay Network，即通用的虚拟化网络模型，不依赖于宿主机底层网络架构，可以适应任何的应用场景，方便快速体验。但是性能较差，因为在原有网络的基础上叠加了一层Overlay网络，封包解包或者NAT对网络性能都是有一定损耗的
2. Underlay Network，即基于宿主机物理网络环境的模型，容器与现有网络可以直接互通，不需要经过封包解包或是NAT，其性能最好。但是其普适性较差，且受宿主机网络架构的制约，比如MAC地址可能不够用

K8S的网络插件主要支持两类：

1. CNI插件：基于v0.4.0版本，本文的主题
2. Kubenet插件：没什么用，通过网桥和host-local CNI插件简单的实现cbr0

Kubelet使用单个默认网络插件，全集群使用一个默认网络。在Kubelet启动时，它会探测插件列表，并且记住它们，在Pod生命周期的适当阶段（仅对于Docker，CRI会自行管理CNI插件）调用选择的插件。两个相关的命令行选项：

--cni-bin-dir  Kubelet启动时从该目录中探测插件
--network-plugin  对于CNI插件，取值 cni

除了实现NetworkPlugin接口：

以创建/清理容器网络，网络插件还需要支持kube-proxy。对于iptables模式的kube-proxy来说，对iptables的依赖是很显然的，因此网络插件应当进行适当的配置，让容器流量对宿主机的iptabels可见。例如，当容器连接到Linux bridge时，必须设置/net/bridge/bridge-nf-call-iptables为1以确保iptables proxy正常工作。使用其它技术时，你同样需要考虑为kube-proxy设置正确的路由。

在K8S中，如果设置--network-plugin=cni则选用CNI作为网络插件。这时Kubelet会读取--cni-conf-dir=/etc/cni/net.d中的CNI配置，来创建Pod网络。配置文件中引用的任何插件都必须存在于--cni-bin-dir=/opt/cni/bin目录下。

如果--cni-bin-dir下有多个插件配置，则Kubelet使用按字典序排名最靠前的那个配置文件。

从CNI 0.2.0开始，除了通过配置文件指定的CNI插件，Kubelet还会使用一个标准的CNI插件lo，它不需要配置。

容器网络接口（Container Network Interface，CNI）是CNCF项目之一，它关注容器的网络连接，负责在容器启动时创建网络资源，在容器删除时清理为其创建的网络资源。由于网络和运行环境关系很密切，因此很必要进行插件化，这是创建CNI项目的缘由。

CNI项目包含两大部分：

1. CNI规范文档：
   1. libcni，Go语言的CNI接口，供运行时调用，转调具体CNI插件
   2. skel，Go语言的CNI插件骨架
   3. https://github.com/containernetworking/cni
2. 一系列参考实现和样例插件：
   1. 接口插件：ptp、bridge、macvlan……
   2. Chained插件：portmap、bandwidth、tuning
   3. https://github.com/containernetworking/plugins

具有以下特点：

1. 供应商中立，不仅仅是为K8S设计。还可以被Mesos、CloudFoundry、podman、CRI-O使用
2. 为网络操作定义了基本的执行流、配置格式
3. 简单、向后兼容

JSON格式，对于任何操作，此配置都从标准输入喂给插件。可以包含标准的配置项、插件特有的配置项，示例：

1. CNI插件是可执行文件，支持ADD / DEL / CHECK / VERSION几个命令
2. 当期望进行网络配置操作时，由容器运行时调用并产生CNI插件进程
3. JSON配置、容器相关的数据，通过stdin传递给CNI插件
4. CNI插件通过stdout报告处理结果 

在未来，CNI可能会支持：

1. 动态更新现有网络配置
2. 网络带宽和防火墙策略的动态策略支持

CNI实现	说明
calico	参考：基于Calico的CNI
galaxy	参考：Galaxy学习笔记
flannel	参考：Flannel学习笔记

规范的版本和CNI库的版本、插件样例/参考实现的版本无关。

为了支持平滑升级，CNI插件的作者应当兼容多版本的CNI规范。特别是，已经发布出去的插件，需要保持对老版本的兼容。插件应该在应答 VERSION命令时，返回类似下面的结构：

对于ADD命令，插件必须尊重网络配置JSON中指定的cniVersion：

1. 如果网络配置没有提供cniVersion字段，假设使用v0.2.0版本，返回结果应该是v0.2.0格式的
2. 如果插件不支持配置指定的版本，应该返回错误

初始版本。

ADD命令正常结果格式：

出错时的结果格式：

该版本主要增加了VERSION命令。该命令的返回结果格式参考上文。

该版本中args被作为一个保留字段。这样可以提供任意的结构化信息，而不是仅仅靠CNI_ARGS传递 k1=v1;k2=v2形式的字符串。

此版本提供了更加丰富的关于容器网络配置的信息，包括网络接口的细节信息，并且支持多个IP地址。

ADD命令正常结果格式：

可以看到，和容器有关的网络接口的详细信息包含在结果中，每个接口都可以包含多个ip信息。

0.3.0版本存在一个BUG，Result结构中的ip字段应当已经被重命名为ips，以保证和IPAM的Result结构一致。v0.3.1解决此问题，并且所有first-party CNI插件（bridge，host-local等）都已经在0.3.1修改为，使用ips字段。

所有v.0.3.0的CNI插件需要注意此差异。

该版本主要增加了CHECK命令。

CNI规范来自rkt网络提案，它规定了Linux下应用容器网络的插件化解决方案。在此规范中，术语：

1. 容器（container）可以认为是Linux网络命名空间的同义词，其关联的单元取决于容器运行时，对于K8S来说是Pod，对于Docker来说是一个裸容器
2. 网络（network）是一组可被唯一寻址的实体，它们能够相互通信。这些实体可以是上一条提到的容器、一个主机、某些网络设备（例如路由器）。容器可以被添加到1-N个网络，或者从中删除

CNI规范规定的是运行时和插件之间的接口。 

1. 在调用任何插件之前，容器运行时必须先为容器创建网络命名空间 
2. 运行时必须确定，容器属于哪些网络，对于这些网络，分别应当调用什么插件
3. 配置文件格式为JSON，包含name、type等必须字段。每次插件调用，参数可以不一样，为此目的，可选的 args字段包含变化的信息
4. 为了将容器添加到每个网络，运行时必须逐个的为每个网络调用插件
5. 在容器销毁时，运行时必须以相反顺序调用插件，将容器从网络断开
6. 运行时可以并行的为多个容器调用插件，但是对于单个容器，必须串行调用
7. 容器必须有唯一性的标识ContainerID，如果需要存储状态，插件必须以网络名、CNI_CONTAINERID、CNI_IFNAME（容器内接口名）作为联合主键
8. 对于任一个上述联合主键，ADD不得被运行时调用两次。这隐含表示：一个容器不得被加入同一网络两次，除非它具有两个网络接口

插件必须实现为可执行文件，rkt/K8S等容器管理系统将通过命令行来调用它们。运行时配置（RuntimeConf）一般通过环境变量传递，网络配置（NetworkConfig）则是通过标准输入喂入。

CNI插件负责把一个网络接口（例如VETH对的一端）插入到容器的网络命名空间，并在宿主机上执行任何必要的操作（例如将VETH对的另外一端接到网桥）。CNI插件还必须给接口分配IP地址，并且通过调用适当的IPAM插件，创建和IPAM一致的路由规则。

该接口负责将容器添加到网络中。

参数：

1. Container ID，容器唯一标识符文本，由运行时分配，不得为空。以数字/字母开头，可以包含 _.-字符
2. Network namespace path，网络命名空间的路径，形式 /proc/PID/ns/net，或者指向该文件的绑定挂载/链接
3. Network configuration，描述网络的JSON配置
4. Extra arguments，基于容器级别的定制化配置参数
5. Name of the interface inside the container，在容器网络命名空间中创建并分配的网络接口的名字，符合Linux接口命名空间，不得超过16字符，不含 / :或空白字符

结果：

1. Interfaces list，取决于插件，返回的信息可能包括沙盒（容器或Hypervisor）接口名、宿主机接口名、接口的硬件地址、沙盒的详细信息
2. IP configuration assigned to each interface，分配到沙盒/宿主机的IPv4/IPv6地址、网关、路由
3. DNS information，包含DNS信息（服务器、domain、search domains、options）的字典

该接口负责将容器从网络中移除。

参数：和ADD相同。

注意点：

1. 所有参数必须和ADD时一致
2. DEL必须清理掉容器持有的、在目标网络中的所有资源
3. 如果存在已知的，针对容器的先前ADD操作，则运行时必须在插件（or all plugins in a chain）JSON中添加prevResult字段，该字段的内容是上一个ADD操作的结果，JSON形式
4. 如果CNI_NETNS或/和prevResult没有提供，则插件应当尽可能清理更多的资源（例如释放IPAM分配的地址）并返回提示操作成功的响应
5. 如果运行时缓存了针对容器的上一个ADD的结果，则它应该在成功DEL后清理掉此缓存

如果某些资源丢失，此接口一般也不返回错误。例如：

1. 即使容器网络命名空间已不存在，IPAM插件也应该释放IP地址并且返回成功，除非网络命名空间对于IPAM管理是关键的
2. bridge插件应当将DEL委托给IPAM插件，并清理自身的资源，即使网络命名空间/容器接口已不存在

该接口报告CNI插件相关的版本信息。没有参数，结果示例：

检查容器的网络是否如预期一样。

参数：和ADD一样， 但是Network configuration包含prevResult字段，存放上一个ADD调用的结果。

结果：返回错误或空。

注意点：

1. 插件必须检查prevResult，确定接口、地址符合预期
2. 插件必须允许后续的chained plugin看到修改后的网络资源，例如路由
3. 如果prevResult中列出的资源（接口、路由、地址）不存在，或者状态异常，应该返回错误
4. 同样的，没有在prevResult中跟踪的网络资源，例如防火墙规则、流量塑形控制规则、IP预留、外部依赖，不存在或状态异常时，也应该返回错误
5. 如果发现容器不可达，应单返回错误
6. 插件需要处理在ADD后紧跟着的CHECK调用，这意味着需要考虑某些异步资源的合理创建延迟
7. 插件需要调用所有被委托插件（例如IPAM）的CHECK，并将错误收集并返回
8. 运行时不会对尚未ADD的容器调用CHECK，也不会对在ADD后进行DEL的容器进行CHECK
9. 如果在配置列表中，disableCheck设置为true，则运行时不会调用CHECK
10. 如果chain中一个插件返回错误，运行时可能选择停止继续迭代后续插件的CHECK
11. 在ADD调用之后，直到DEL调用之前，运行时都可以调用CHECK
12. 运行时可以假设CHECK失败的容器处于不可恢复的错误配置状态中

如果ADD操作成功，插件应该以0退出，并且在标准输出上打印JSON。JSON中ips、dns部分必须和IPAM插件输出的一致，interfaces数组则需要插件填写，因为IPAM插件对接口无感知：

如果ADD操作失败，则应该以非0退出，并打印： 

网络配置为JSON格式，可以存放在磁盘上，或者由运行时从其它源动态生成。

插件可以定义自己的字段，知名字段包括：

字段	说明
cniVersion	字符串。当前配置遵循的CNI规范版本
name	字符串。网络名，在主机范围内必须唯一
type	字符串。CNI插件的可执行文件的名字
args	字典，可选。由运行时提供的额外参数。例如可以传递一组标签 此字段可以传入任何值
ipMasq	布尔，可选。如果插件支持，则在宿主机上为此网络设置IP遮掩（动态SNAT）。如果宿主机需要充当容器IP的网关，则为true
ipam	字典，可选。IPAM相关的配置： type：IPAM插件的可执行文件名
dns	字典，可选。DNS相关配置： nameservers：此网络可以感知的，优先级排序的DNS服务器列表 domain：用于短名查找的本地域后缀 search：字符串列表，优先级排序的短名查找DNS后缀 options：传递给resolver的选项
runtimeConfig	知名非标准字段。运行时动态填充的信息应该存放在此 通过列出capabilities，插件可以请求运行时填充必要的动态信息
capabilities	知名非标准字段。和runtimeConfig配合使用，提示运行时插件具有哪些特性，运行时因而能够提供这些特性所需的动态参数 例如，一个端口映射插件，可以这样配置： JSON 1 2 3 4 5 {   "name" : "ExamplePlugin",   "type" : "port-mapper",   "capabilities": {"portMappings": true} } 这样，运行时传递给插件的、填充后的网络配置可能如下： JSON 1 2 3 4 5 6 7 8 9 {   "name" : "ExamplePlugin",   "type" : "port-mapper",   "runtimeConfig": {     "portMappings": [       {"hostPort": 8080, "containerPort": 80, "protocol": "tcp"}     ]   } }

插件可以定义额外的字段，如果配置文件中传入它不能理解的字段，可能会报错。例外是args字段，可以配置任何值。 

Arg	说明
labels	传递一系列键值对给插件 JSON 1 2 3 4 "labels" : [   { "key" : "app", "value" : "myapp" },   { "key" : "env", "value" : "prod" } ]
ips	用于请求插件分配静态IP地址 JSON 1 "ips": ["10.2.2.42/24", "2001:db8::5"]

Capability	目的/runtimeConfig
portMappings	传递宿主机端口、容器网络命名空间端口的映射关系 JSON 1 2 3 4 [   { "hostPort": 8080, "containerPort": 80, "protocol": "tcp" },   { "hostPort": 8000, "containerPort": 8001, "protocol": "udp" } ]
ipRanges	动态配置分配的IP地址的范围。对于那些负责管理IP地址池（但是不管理单个IP）的运行时，可以传递这些信息给插件 JSON 1 2 3 4 5 [   [     { "subnet": "10.1.2.0/24", "rangeStart": "10.1.2.3", "rangeEnd": 10.1.2.99", "gateway": "10.1.2.254" }   ] ]
bandwidth	用于动态配置网络接口的带宽限制。单位bits/sec JSON 1 { "ingressRate": 2048, "ingressBurst": 1600, "egressRate": 4096, "egressBurst": 1600 }
dns	由运行时动态提供DNS信息 JSON 1 2 3 4 {   "searches" : [ "internal.yoyodyne.net", "corp.tyrell.net" ]   "servers": [ "8.8.8.8", "10.0.0.10" ] }
ips	由运行时动态的给容器网络接口分配IP地址。如果容器运行时具有IP分配能力，可以传递 JSON 1 [ "10.10.0.1/24", "3ffe:ffff:0:01ff::1/64" ]
mac	容器运行时可以将MAC传递给那些需要mac作为输入的CNI插件 JSON 1 "c2:11:22:33:44:55"
aliases	提供映射到容器IP地址的别名，便于位于同一个容器网络中的实体可以用此名字访问容器 JSON 1 ["my-container", "primary-db"]

bridge：

macvlan：

使用网络配置列表，可以针对单个容器、按照特定顺序依次调用多个CNI插件，并将前一个插件的结果传递给后一个插件。

注意：网络配置列表的目的并不是为了将容器加入到多个网络，而是为了实现端口映射、流量塑形等额外能力。运行时调用时不会为每个插件指定一个网络接口名称。

可用字段：

字段	说明
cniVersion	字符串。当前配置遵循的CNI规范版本
name	字符串。网络名，在主机范围内必须唯一
disableCheck	布尔。如果为true则运行时不会调用CHECK
plugins	标准的CNI插件的配置列表

运行时调用单个插件时：

1. 会将name, cniVersion换成列表中的name, cniVersion
2. 会将上一个插件的结果写入到prevResult字段
3. 在DEL时，调用插件的顺序和ADD相反
4. 在相同环境下调用所有插件
5. 如果出错，则终止后续插件调用

CNI插件可能需要为网络接口分配IP地址，并为网络接口安装相关的路由规则。为了支持不同的IP管理需求（DHCP、host-local），让IP分配和CNI插件基本功能解耦，规范定义了新的插件类型：IPAM Plugin。调用IPAM Plugin是CNI插件的职责，它应该在适当的时机发起调用，为网络接口获得IP地址。

IPAM插件需要决定：

1. 网络接口IP/子网
2. 网关
3. 路由

并将这些信息返回给“主”CNI插件来应用。IPAM插件的信息来源可能是DHCP协议、本地文件系统中的数据、网络配置ipam段中的配置信息。

类似于CNI插件，IPAM插件也是通过运行可执行文件来调用的、参数也是通过stdin传递。 IPAM插件必须接收传递给CNI插件的全部环境变量。

如果调用成功，应当以0退出，并跟着如下格式的JSON：

上述返回结果类似于CNI的返回结果，但是不包含interfaces键，IPAM不需要关心网络接口的信息，将IP配置给网络接口是“主”插件的职责。

错误码	说明
1	不兼容的CNI版本
2	网络配置中包含不支持的字段，错误消息中应该指明不支持的键值
3	未知或不存在的容器，隐含运行时不需要进行任何容器网络清理
4	无效的必须环境变量，例如CNI_COMMAND、CNI_CONTAINERID
5	I/O错误，例如无法从stdin读取网络配置
6	无法解析网络配置
7	无效网络配置
11	出现临时性的错误，提示运行时后续重试

对于Kubelet来说，CNI的网络配置通常是静态文件，那么针对容器/Pod的运行时参数，都需要通过环境变量传递。

即使使用了插件列表，Kubelet也仅会执行一次CNI调用，这些环境变量对应RuntimeConfig的字段。每个插件看到的都是一样的值。

例如CNI_IFNAME，它总是eth0，是Kubelet给的一个提示，容器的主网络接口的名字是什么。至于CNI插件是否使用eth0，会不会创建eth1，并不受限制。

环境变量	说明
CNI_PATH	从什么目录寻找CNI插件，默认 /opt/cni/bin
CNI_CONTAINERID	容器唯一标识
CNI_NETNS	所在网络命名空间
CNI_IFNAME	网络接口名称，通常是eth0
CNI_COMMAND	调用的CNI接口，例如ADD、DEL、CHECK
CNI_ARGS	CNI参数，格式为 key1=val1;key2=val2 对于Kubelet来说，它肯定会传递以下键： K8S_POD_NAMESPACE  当前Pod所属命名空间 K8S_POD_NAME  当前Pod的名字 K8S_POD_INFRA_CONTAINER_ID Pod对应的基础容器的ID
NETCONFPATH	CNI网络配置所在目录，默认  /etc/cni/net.d

要开发自己的CNI插件，应当先去阅读CNI规范、样例/参考实现。 

这是一个小工具，可以执行CNI配置，在已存在的网络命名空间中添加、删除网络接口。

cnitool会搜索 $NETCONFPATH下面所有的 *.conf或 *.json文件，加载它们，然后寻找网络名称和传递给cnitool匹配的网络配置。

cnitool是参考实现的一部分，因此你可以直接构建参考实现，以获得cnitool： 

首先需要创建网络命名空间： 

并创建CNI网络配置：

然后调用cnitool：

检查配置是否符合预期：

检查命名空间中的网络接口：

清理：

CNI项目提供了一个代码库，其中包含了若干参考实现。本文后面的内容会分析其中一些CNI插件的源代码。

构建、安装了参考实现，或者你自己编写的CNI插件后，可以利用参考实现项目的scripts/目录中的priv-net-run.sh、docker-run.sh来执行插件，以进行快速的验证。

你需要为被测试的CNI插件创建网络配置：

调用命令：

你可以在私有网络命名空间下看到和上面两个CNI配置对应的网络接口。 

创建并配置网络命名空间，然后在其中运行Docker容器：

libcni.CNI，这是CNI提供的一套接口，供容器运行时调用，实现CNI相关的操控。接口规格如下：

NetworkConfigList、NetworkConfig就对应了规范中的网络配置列表、网络配置，JSON部分直接存放在字节数组：

网络配置，转换为的结构：

RuntimeConf则包含了一次CNI调用中，除了网络配置之外的参数信息。通常由容器运行时根据上下文来构建：

上一个CNI插件的调用结果，存放在此结构中：

dockershim是kubelet中的一个模块，Kubelet通过CRI gRPC调用进程内的dockershim，后者则将CRI请求适配为对Docker守护进程的请求。可以认为dockershim是一个容器运行时。

在创建Pod时，NetworkPlugin.SetUpPod方法会被调用，来为Pod安装网络：

此包提供了一些（通过命令行）调用CNI插件的函数。

下面这个函数，根据名字查找CNI插件，并且传递网络配置、来自环境变量的CNI参数，调用插件的ADD命令：

ExecPluginWithResult / ExecPluginWithoutResult函数发起CNI调用：

 

参考实现的测试用例基于Ginkgo，本节阅读loopback插件的测试用例，依此了解如何调用、测试CNI插件。

这个包提供了CNI插件开发的骨架代码，它实现了参数解析和校验，你可以将其作为库使用，简化CNI开发。

有了skel，我们实现自己的CNI插件时，只需要编写几个函数就可以了。 

这个插件很简单，就是在命名空间中添加一个lo接口：

使用该插件，同一主机上的所有容器被连接到一个网桥上，网桥位于宿主机的网络命名空间中。一个veth对，一端接着网桥，另一端接着容器。IP地址仅仅在veth对连接容器的那一端分配。 

网桥自身也可以分配IP地址，这样它可以作为所有容器的网关。如果不分配，那么网桥工作在纯L2模式，如果容器有对外访问需求（也就是不仅仅需要和本机其它容器通信），则网桥需要桥接到宿主机的某个网络接口。

使用此插件时，需要指定网桥的名字。示例配置：

纯L2模式配置：