CNI 规范版本升级指南:从 0.3.0 到 1.0 的插件与运行时迁移实战
CNI 规范版本升级指南:从 0.3.0 到 1.0 的插件与运行时迁移实战
CNI(Container Network Interface)规范经历了 0.1.0、0.2.0、0.3.0/0.3.1、0.4.0 直至 1.0.0/1.1.0 的多次演进,每一次版本升级都对网络配置格式、插件执行协议与 Go 库 API 产生实质影响。本文以仓库中的 spec-upgrades.md 为核心脉络,结合 SPEC.md 与 pkg/types、pkg/version、pkg/skel、libcni 等源码实现,完整讲解各版本的关键变更、Result 结构的字段演进、版本协商与转换机制,并为 CNI 使用者、插件作者和运行时作者分别给出可落地的升级路径。读完本文,你将能准确理解 CNI 各规范版本间的差异,掌握让插件支持多版本、让运行时正确处理版本化结果的具体方法,并能在自己的项目中安全完成版本迁移。
一、CNI 规范版本演进全景
CNI 规范(SPEC.md)与仓库的 GitHub Release 版本是独立编号的。例如 Release v0.4.0 支持的是规范版本 v0.2.0,而 Release v0.5.0 才支持规范 v0.3.0。理解这一关系至关重要:升级容器运行时或插件二进制时,应关注其声明的"支持的 CNI 规范版本",而非仓库自身的 Release 号。
从当前仓库的 pkg/version/version.go 可以看到,本库实现的规范版本已到 1.1.0(Current() 返回 "1.1.0"),version.All 声明的支持版本为 0.1.0, 0.2.0, 0.3.0, 0.3.1, 0.4.0, 1.0.0, 1.1.0。历次规范升级的核心变更概览如下:
| 规范版本 | 核心变更 |
|---|---|
| 0.3.0 | Result 引入 interfaces 与 ips 字段,支持多 IP/多接口描述;但存在 ip 字段名未改干净的笔误 |
| 0.3.1 | 修正 Result 字段名为 ips(与 0.3.0 之间仅此一处差异) |
| 0.4.0 | 新增 CHECK 动词与 disableCheck 配置标志;Result 类型不变 |
| 1.0.0 | 移除非 List(non-List)配置;移除 interfaces 数组中冗余的 version 字段;/pkg/types/current 包不复存在 |
| 1.1.0 | 引入 GC、STATUS 动词(源码 pkg/skel/skel.go 的命令分发中可见) |
二、升级到 CNI v1.0:移除与重构
CNI v1.0 带来了两项结构性变化:
- 非 List 配置被移除:v1.0 起,网络配置必须以"插件列表(List)"的形式组织(
NetConfList,参见 pkg/types/types.go 中的NetConfList结构),单插件配置(PluginConf)只能作为 List 中的一项存在。 interfaces数组中的version字段被移除:该字段是冗余的,v1.0 之后的接口描述不再携带版本信息。对照 pkg/types/100/types.go 中的Interface结构(name、mac、mtu、sandbox、socketPath、pciID),确实已无version字段。
/pkg/types/current 不再存在
v1.0 最重大的库级变化是:/pkg/types/current 包被删除。此前 types/current 隐式地指向"当前最新版本",这会导致运行时在 revendor 本库到其他项目时因版本漂移而产生难以排查的代码破损。删除后,运行时与插件必须显式选择自己支持的规范版本,把"插件支持哪些 CNI 规范版本"的决策权交还给插件作者。
因此,Go 代码中的 import 必须改为显式版本路径,例如:
import (
cniv1 "github.com/containernetworking/cni/pkg/types/100"
)
当前仓库中并存 pkg/types/020(0.1.0/0.2.0)、pkg/types/040(0.3.0/0.3.1/0.4.0)、pkg/types/100(1.0.0/1.1.0)三个版本化子包,分别对应各自的 Result 具体结构。
三、CNI v0.4:CHECK 动词与 disableCheck
CNI v0.4 引入了两个重要能力,且未对 Result 类型做任何修改:
- 新增
CHECK动词:运行时现在可以向插件发出CHECK请求,验证某个容器网络挂载(attachment)的状态是否仍然正确——例如网桥是否还存在、IP 是否仍然绑定。 - 新增配置标志
disableCheck:在配置中设置为true时,运行时必须跳过对该网络配置的CHECK调用,用于规避"已知插件组合会产生虚假错误"的场景。这一点在 SPEC.md 中有明确规定:"A runtime must not callCHECKifdisableCheckis set totruein the configuration"。
从源码看,disableCheck 是 NetConfList 结构上的布尔字段(pkg/types/types.go),libcni 的 NetworkConfigList 同样携带 DisableCheck bool(libcni/api.go)。CHECK 命令在插件侧的入口位于 pkg/skel/skel.go 的命令分发逻辑中:插件收到 CNI_COMMAND=CHECK 时,会先通过 version.GreaterThanOrEqualTo(configVersion, "0.4.0") 校验配置版本是否允许 CHECK,再在插件的支持版本列表中寻找不低于配置版本的支持项并调用 funcs.Check 回调。
四、0.3.0 与 0.3.1:Result 结构演进(ip → ips)
0.3.0 规范引入了丰富的网络配置信息:容器网络接口的详细描述、多 IP 地址支持等。但 0.3.0 规范本身包含一个小错误——Result 结构的 ip 字段本应改名为 ips(以与 IPAM 结果结构命名保持一致),这一改名在支持多 IP/多接口时被遗漏了。结果是:
- 所有第一方 CNI 插件(bridge、host-local 等)都按
ips实现(与 0.3.0 规范文本不一致); - 大多数第三方插件当时尚未升级到 0.3.0,因此几乎没有用户实际受影响;
- 0.3.1 规范修正了 Result 结构,正式采用
ips字段名。0.3.0 与 0.3.1 之间仅此一处差异。
对照源码,types040.Result 与 types100.Result 都使用 IPs <a href="https://link.gitcode.com/i/c65edc97e13e68c8864f9c5ca1d534c9" target="_blank">]*IPConfig(JSON 标签 ips),而 0.2.0 及更早的 types020.Result 使用 IP4/IP6 两个独立结构(JSON 标签 ip4/ip6),见 [pkg/types/020/types.go。这正是字段演进在代码层面的完整映射。
五、面向 CNI 使用者的升级要点
如果你是维护 CNI 配置文件(供容器运行时使用)的使用者,升级时只需把握几条原则:
- 确保配置文件包含
cniVersion字段,且该版本被你的容器运行时和 CNI 插件同时支持。 - 没有版本字段的配置文件应视为 0.2.0。从源码看,pkg/types/create/create.go 的
DecodeVersion在cniVersion为空时同样默认返回"0.1.0"(配置默认值取 0.1.0/0.2.0 取决于解析入口,规范层面以文档声明为准——文档明确指示视为 0.2.0)。 - 配置版本应取插件支持的最低公共版本(lowest common version),以保证配置对所有插件都可用。
- 部署前务必先在测试环境验证插件升级,可借助 cnitool 工具完成无需容器运行时的插件联调。
SPEC.md 提供了单插件与链式插件列表两种示例配置。链式配置示例(dbnet)如下,其中 cniVersion、cniVersions 与 plugins 数组是关键字段:
{
"cniVersion": "1.1.0",
"cniVersions": ["0.3.1", "0.4.0", "1.0.0", "1.1.0"],
"name": "dbnet",
"plugins": [
{
"type": "bridge",
"bridge": "cni0",
"ipam": {
"type": "host-local",
"subnet": "10.1.0.0/16",
"gateway": "10.1.0.1",
"routes": [{"dst": "0.0.0.0/0"}]
},
"dns": { "nameservers": [ "10.1.0.1" ] }
},
{
"type": "tuning",
"capabilities": { "mac": true },
"sysctl": { "net.core.somaxconn": "500" }
},
{
"type": "portmap",
"capabilities": {"portMappings": true}
}
]
}
六、面向插件作者的升级指南
语言无关的通用指南(所有插件)
为了平滑升级,已有安装基础的插件应同时支持多个版本的 CNI 规范——尤其应在保持旧版本兼容的同时新增对 1.0.0 的支持。这需要两步改造:
第一步:通过 VERSION 命令通告支持的规范版本。插件响应 VERSION 命令时输出如下 JSON:
{
"cniVersion": "1.0.0",
"supportedVersions": [ "0.1.0", "0.2.0", "0.3.0", "0.3.1", "0.4.0", "1.0.0" ]
}
源码层面的对应物是 pkg/version/plugin.go 中的 pluginInfo 结构(JSON 标签 cniVersion 与 supportedVersions)及其 Encode 方法;skel 在收到 CNI_COMMAND=VERSION 时直接调用 versionInfo.Encode(t.Stdout) 输出。
第二步:ADD 命令必须尊重网络配置 JSON 中的 cniVersion 字段。该字段是插件必须以何种格式返回结果的请求:
cniVersion字段缺失 → 按 0.2.0 处理,返回 0.2.0 格式的结果 JSON;- 插件不支持该版本 → 必须返回错误;
- 否则 → 以请求的格式返回 CNI Result。
例如,插件通过 VERSION 通告支持 0.2.0 与 0.3.0,当收到 cniVersion 为 0.2.0 的配置时,就必须返回符合 0.2.0 规范的结果 JSON。更早版本的 Result 格式可从 SPEC.md 的 git 历史中查阅。
Go 插件具体指南
Go 插件可复用本仓库的 Go 包。对插件作者而言最大的变化是:types.Result 已从具体结构变为接口,由 pkg/types/100、pkg/types/040、pkg/types/020 三个子包中的具体结构体实现。
推荐实践:
- 插件内部统一使用最新规范版本的结构(如
types/100)构造结果; - 仅在需要向 stdout 输出结果 JSON 时,才按请求的
cniVersion做一次版本转换; - 用库函数
types.PrintResult()一步完成"转换 + 打印"。
types.PrintResult 的实现见 pkg/types/types.go:它先调用 result.GetAsVersion(version) 得到目标版本的结果,再调用 Print() 输出到 stdout。转换器由各版本包的 init() 注册到 pkg/types/internal/convert.go 的全局注册表(如 types100 注册了 0.1/0.2/0.3/0.4 → 1.x 的上转换,以及 1.0/1.1 → 各旧版本的下转换)。
此外,插件应通过 skel.PluginMain() 的第三个参数通告支持的规范版本。一个完整的示例:
import (
"github.com/containernetworking/cni/pkg/skel"
"github.com/containernetworking/cni/pkg/types"
current "github.com/containernetworking/cni/pkg/types/100"
"github.com/containernetworking/cni/pkg/version"
)
func cmdAdd(args *skel.CmdArgs) error {
// determine spec version to use
var netConf struct {
types.NetConf
// other plugin-specific configuration goes here
}
err := json.Unmarshal(args.StdinData, &netConf)
cniVersion := netConf.CNIVersion
// plugin does its work...
// set up interfaces
// assign addresses, etc
// construct the result
result := ¤t.Result{
Interfaces: []*current.Interface{ ... },
IPs: []*current.IPs{ ... },
...
}
// print result to stdout, in the format defined by the requested cniVersion
return types.PrintResult(result, cniVersion)
}
func main() {
skel.PluginMain(cmdAdd, cmdDel, version.All)
}
skel.PluginMain(pkg/skel/skel.go)会解析 CNI_COMMAND 等环境变量与 stdin 配置,在调用回调前通过 VersionReconciler.Check 校验配置版本是否在插件支持列表内(见 pkg/version/reconcile.go),版本不匹配时返回 ErrIncompatibleCNIVersion(错误码 1)。注意当前源码中 skel.PluginMain 的签名已扩展为 PluginMain(cmdAdd, cmdCheck, cmdDel, versionInfo, about),文档中的 skel.PluginMain(cmdAdd, cmdDel, version.All) 是早期简写形态,实际实现时请以本仓库 API 为准。
如果插件的结果来自被委托的 IPAM 插件,可这样构造结果:
ipamResult, err := ipam.ExecAdd(netConf.IPAM.Type, args.StdinData)
result, err := current.NewResultFromResult(ipamResult)
NewResultFromResult(pkg/types/100/types.go)内部调用 convert.Convert(result, ImplementedSpecVersion),将任意版本的 Result 统一转换为 1.0/1.1 格式的具体结构,方便插件继续操作字段。
七、面向运行时作者的升级指南
语言无关的通用指南(所有运行时)
支持多个 CNI 规范版本:已有安装基础的运行时应在保持旧版本兼容的同时,新增对 0.3.0 及之后版本的支持,且应能同时调用新旧插件并处理两种结果。调用插件时,运行时必须在网络配置 JSON 块中通过 cniVersion 字段指定期望的响应格式;插件会按该版本返回对应格式的 Result,运行时必须正确解析处理。
处理版本不兼容错误:插件可能返回"不支持请求的 CNI 版本"错误(参见 SPEC.md 的 Well-known Error Codes 一节),例如:
{
"cniVersion": "0.2.0",
"code": 1,
"msg": "CNI version not supported"
}
此时运行时可以用更低的 CNI 规范版本重试,或采取其他降级措施。从 pkg/types/types.go 的错误码定义看,ErrIncompatibleCNIVersion 正是错误码 1,其余常见错误码还包括 ErrUnsupportedField(2)、ErrUnknownContainer(3)、ErrInvalidEnvironmentVariables(4)、ErrIOFailure(5)、ErrDecodingFailure(6)、ErrInvalidNetworkConfig(7)、ErrInvalidNetNS(8)等。
(可选)发现插件支持的版本:运行时可通过 VERSION 命令探测插件支持的规范版本。VERSION 命令自 v0.2.0 起加入,旧插件可能不响应;若未获得成功响应,应假定该插件仅支持 v0.1.0。
处理 v0.3.0+ 结果中缺失的接口数据:0.3.0 及之后的 ADD 结果新增了 interfaces 字段,ips 中的每条 IP 可通过 interface 子字段(数值索引)指明其所属接口。但部分兼容 v0.3.0+ 的插件可能省略 interfaces 字段,或将 interface 索引设为 -1。运行时应当优雅处理这种情况;除非确有理由依赖接口数据,否则应给出有助于诊断的错误信息。
Go 运行时具体指南
对 Go 运行时而言,库层面最大的变化同样集中在 types 包的重构:顶层 types.Result 变为不透明接口而非结构体,其他包(如高层 libcni 包)的 API 均已改为使用该接口;具体类型则按版本拆分为子包。
向上转换旧版结果到 0.3.0+ 时,0.3.0+ 新增的字段(如 interfaces)可能为空;反之,向下转换 0.3.0+ 结果到旧版本时,这些字段中的数据会丢失。完整的转换矩阵如下:
| From | 0.1 | 0.2 | 0.3 | 0.4 | 1.0 |
|---|---|---|---|---|---|
| To 0.1 | ✔ | ✔ | x | x | x |
| To 0.2 | ✔ | ✔ | x | x | x |
| To 0.3 | ✴ | ✴ | ✔ | ✔ | ✔ |
| To 0.4 | ✴ | ✴ | ✔ | ✔ | ✔ |
| To 1.0 | ✴ | ✴ | ✔ | ✔ | ✔ |
✔:无损转换 ✴:转换为更高版本时输出可能包含空字段 x:转换为更低版本时丢失部分数据
这张矩阵与实际代码完全吻合:types040.convertTo02x(pkg/types/040/types.go)在向下转换时只保留每个 IP 版本的第一条地址并明确报错"cannot convert: no valid IP addresses",且 0.2.0 及更早版本无法表达接口信息(故 0.3+ → 0.1/0.2 标记为 x);types100.convertFrom02x 则经由 0.4.0 中转完成向上转换,接口字段可能为空(故 0.1/0.2 → 0.3+ 标记为 ✴)。
运行时应使用 current.NewResultFromResult() 将不透明的 types.Result 转换为具体的 current.Result 结构后操作字段:
// runtime invokes the plugin to get the opaque types.Result
// this may conform to any CNI spec version
resultInterface, err := libcni.AddNetwork(ctx, netConf, runtimeConf)
// upconvert result to the current 1.0 spec
result, err := current.NewResultFromResult(resultInterface)
// use the result fields ....
for _, ip := range result.IPs { ... }
libcni 的 CNI 接口(libcni/api.go)提供 AddNetwork、CheckNetwork、DelNetwork 等顶层调用,并配套 AddNetworkList、CheckNetworkList、DelNetworkList 处理链式配置;所有调用统一返回 types.Result 接口,由运行时按需转换。
八、升级实施建议与验证路径
- 使用者:先确认运行时与插件共同支持的最低规范版本,据此设置配置的
cniVersion;升级插件后逐一用 cnitool 对单插件与链式配置做ADD/DEL冒烟测试。 - 插件作者:让
VERSION响应覆盖尽可能多的历史版本;ADD内部用types/100构造结果,出口处经types.PrintResult(result, cniVersion)按请求版本输出;用skel.PluginMain统一管理参数解析、版本协调与错误输出。 - 运行时作者:显式引入目标版本包(如
types/100)而非types/current;调用插件后在NewResultFromResult处统一收敛版本;对code: 1的版本不兼容错误实现降级重试;对缺失的interfaces数据保持宽容。
仓库中的 conf_test.go、pkg/types/types_test.go 以及各版本子包的测试(pkg/types/100/types_test.go、pkg/types/040/types_test.go、pkg/types/020/types_test.go)覆盖了跨版本转换与配置解析的关键路径,可作为理解与验证版本行为的第一手参考。
九、总结
CNI 规范升级的核心脉络可以概括为三条主线:Result 结构的版本化演进(从 ip4/ip6 到 ips + interfaces,再到移除冗余 version 字段)、协议动词的逐步扩充(VERSION、CHECK、GC、STATUS)、以及 Go 库 API 从"隐式 current"到"显式版本化"的转变。对插件作者与运行时作者而言,最稳妥的策略始终是"同时支持多个版本,内部用最新版本构造/处理,边界处按请求版本转换"。借助 pkg/types/internal/convert.go 的转换注册机制与 pkg/version 的版本协调工具,这套多版本兼容体系在代码层面已经成熟,直接复用即可大幅降低升级成本。