《CNI specification》翻译

Overview

本文提出了一个通用的基于插件的Linux容器网络解决方案，容器网络接口，CNI。它脱胎于旨在满足大多数rtk网络设计的rtk Networking Proposal。

首先，我们对如下两个名词进行具体的定义：

• container可以认为是与Linux network namespace是同义的。而一个network namespace具体对应什么，则与具体的容器运行时有关：例如，在rtk中，每个pod运行在一个单独的network namespace中。但是在docker中，network namespace存在于每个独立的Docker容器中
• network代表了一组可以独立寻址并且可以互相交互的实体。这些实体既可以是一个单独的容器（如上所述），一台机器，或者其他什么网络设备（例如，一台路由器）。container可以加入一个或多个network，也可以从一个或多个network中移除。

本文旨在说明容器运行时和插件之间的接口。同时，可能还有些众所周知的字段，runtime也想传递给底层的插件，不过这些内容并不在本文中进行描述。

General consideration

首先容器运行时需要为container新建一个network namespace。之后，它需要决定该container属于哪些network，对于每个network还需要确定对应执行哪些插件。network configuration是以JSON格式存在的，很容易被存储在文件中。配置中需要包含一些必须的字段，例如，"name"，“type”以及相应的插件必须的字段。同时，network configuration允许其中的字段在不同的调用间发生改变。因此，存在一个可选的"args"字段用于存放异变的信息。最后，容器运行时通过顺序地调用相应的插件来创建相应的network。当container的生命周期结束时，运行时再以相反的顺序调用插件，将它们从networks中移除。

CNI Plugin

Overview

每个CNI插件都是以一个能被容器管理系统（比如，rkt或者Docker）调用的可执行文件的形式存在的。

CNI插件负责将一个network interface插入container network namespace（比如，veth pair的其中一端）并且在宿主机中做一些必要的配置（例如将veth的另一端加入bridge中）。接着通过调用适当的IPAM插件，将IP赋给interface并且设置路由。

Parameters

CNI插件支持如下三种操作：

• 将container加入network（Add）：
  • Parameters:
    • Version. 调用者使用的CNI 配置的版本信息
    • Container ID. 这个字段是可选的，但是建议使用，在容器活着的时候要求该字段全局唯一的。比如，存在IPAM的环境可能会要求每个container都分配一个独立的ID，这样每一个IP的分配都能和一个特定的容器相关联。例如，在appc implementations中，container ID其实就是pod ID
    • Network namespace path. 这个字段表示要加入的network namespace的路径。例如，/proc/[pid]/ns/net或者对于该目录的bind-mount/link。
    • Network configuration. 这是一个JSON文件用于描述container可以加入的network，具体内容在下文中描述
    • Extra arguments. 该字段提供了可选的机制，从而允许基于每个容器进行CNI插件的简单配置
    • Name of the interface inside the container. 该字段提供了在container （network namespace）中的interface的名字；因此，它也必须符合Linux对于网络命名的限制
  • Result:
    • Interface list. 根据插件的不同，这个字段可以包括sandbox (container or hypervisor) interface的name，以及host interface的name，每个interface的hardware address，以及interface所在的sandbox（如果存在的话）的信息。
    • IP configuration assigned to each interface. IPv4和/或者IPv6地址，gateways以及为sandbox或host interfaces中添加的路由
    • DNS inormation. 包含nameservers，domains，search domains和options的DNS information的字典
• 将container从network中删除（Delete）：
  • Parameter:
    • Version. 调用者使用的CNI 配置的版本信息
    • ContainerID. 定义同上
    • Network namespace path. 定义同上
    • Network configuration. 定义同上
    • Extra argument. 定义同上
    • Name of the interface inside the container. 定义同上
• 版本信息
  • Parameter: 无
  • Result: 返回插件支持的所有CNI版本　　

{
  "cniVersion": "0.3.1", // the version of the CNI spec in use for this output
  "supportedVersions": [ "0.1.0", "0.2.0", "0.3.0", "0.3.1" ] // the list of CNI spec versions that this plugin supports
}

　　

最终executable command-line API会以network的type作为名字去调用相应的插件。它首先会在一系列预先定义好的目录中查找该可执行文件。一旦找到，它就会用以下的环境变量作为参数去调用该可执行文件：

• CNI_COMMAND: 表示进行的操作；ADD, DEL或者VERSION
• CNI_CONTAINERID: Container ID
• CNI_NETNS: network namespace文件的路径
• CNI_IFNAME: 创建的interface的名字，插件必须使用这个名字，否则返回错误
• CNI_ARGS: 在调用时用户传入的额外的参数，由以分号分割的，字母数字键值对组成，例如，"FOO=BAR;ABC=123"
• CNI_PATH:用于查找CNI插件的可执行文件的路径列表，在Linux中，路径之间由":"分割，在Windows中用";"分割

以JSON形式存在的network configuration将以stdin的方式进入插件。这意味着它并不和磁盘上某个特定的文件绑定，因此它所包含的信息也能在每次调用之后发生改变

Result

需要注意的是IPAM插件返回的是一个精简的Result结构，对它的描述放在IP Allocation中

当执行的是ADD命令时，如果返回值是0，并且有如下的JSON输出到stdout，那么说明执行成功了。在IPAM插件返回的结果中同样需要对ips和dns字段进行适当的填充，但是interface字段除外，因为IPAM插件并不应该意识到interface的存在

{
  "cniVersion": "0.3.1",
  "interfaces": [                                            (this key omitted by IPAM plugins)
      {
          "name": "<name>",
          "mac": "<MAC address>",                            (required if L2 addresses are meaningful)
          "sandbox": "<netns path or hypervisor identifier>" (required for container/hypervisor interfaces, empty/omitted for host interfaces)
      }
  ],
  "ips": [
      {
          "version": "<4-or-6>",
          "address": "<ip-and-prefix-in-CIDR>",
          "gateway": "<ip-address-of-the-gateway>",          (optional)
          "interface": <numeric index into 'interfaces' list>
      },
      ...
  ],
  "routes": [                                                (optional)
      {
          "dst": "<ip-and-prefix-in-cidr>",
          "gw": "<ip-of-next-hop>"                           (optional)
      },
      ...
  ]
  "dns": {
    "nameservers": <list-of-nameservers>                     (optional)
    "domain": <name-of-local-domain>                         (optional)
    "search": <list-of-additional-search-domains>            (optional)
    "options": <list-of-options>                             (optional)
  }
}

cniVersion以Semantic Version 2.0的格式指定了插件使用的CNI版本。interfaces描述了插件创建的network interfaces。如果指定了CNI_IFNAME，那么插件必须用该名字对sandbox/hypervisor interface进行命名，否则返回错误

• mac （string）：interface的hardware address。如果对于插件来说L2地址是没有意义的，那个该字段是可选的
• sandbox （string）：container/namespace-based environment需要返回sandbox所在的network namespace的完整路径。Hypervisor/VM-based插件需要返回一个唯一的ID，代表新建的interface所在的virtualized sandbox。

ips字段包含了一系列的IP配置信息，详情参见IP well-known structure。dns字段包含了一个由通用的DNS信息组成的字典。详情参见DNS well-known structure。specification中并没有这些信息到底应该被如何使用。例如产生一个/etc/resolv.conf文件插入容器文件系统中，或者在宿主机运行一个DNS forwarder。

如果遇到错误将得到一个非零的返回值以及如下形式的JSON输出：

{
  "cniVersion": "0.3.1",
  "code": <numeric-error-code>,
  "msg": <short-error-message>,
  "details": <long-error-message> (optional)
}

cniVersion以Semantic Version 2.0的格式指定了插件使用的CNI版本。Error codes的0-99用于一些众所周知的错误（详情参见Well-known Error Codes）。超过100的值可以用于插件特定的错误。

另外，stderr可以用于输出一些unstructured output，例如logs。

Network Configuration

network configuration以JSON格式进行描述。configuration可以被存储在磁盘中或者通过容器运行时以其他方式产生。接下来是一些比较重要的字段：

• cniVersion（string）：cniVersion以Semantic Version 2.0的格式指定了插件使用的CNI版本
• name （string）：Network name。这应该在整个管理域中都是唯一的
• type （string）：代表了CNI插件可执行文件的文件名
• args （dictionary）：由容器运行时提供的可选的参数。比如，可以将一个由label组成的dictionary传递给CNI插件，通过在args下增加一个labels字段
• ipMasqs (boolean)：可选项（如果插件支持的话）。为network在宿主机创建IP masquerade。这个字段是必须的，如果需要将宿主机作为网关，从而能够路由到容器分配的IP
• ipam：由特定的IPAM值组成的dictionary
  • type （string）：表示IPAM插件的可执行文件的文件名
• dns：由特定的DNS值组成的dictionary
  • nameservers (list of strings)：一系列对network可见的，以优先级顺序排列的DNS nameserver列表。列表中的每一项都包含了一个IPv4或者一个IPv6地址
  • domain （string）：用于查找short hostname的本地域
  • search （list of strings）：以优先级顺序排列的用于查找short domain的查找域。对于大多数resolver，它的优先级比domain更高
  • options（list of strings）：一系列可以被传输给resolver的可选项

插件可能会定义它们自己能接收的额外的字段，但是遇到一个未知的字段可能会产生错误。例外的是args字段，它可以被用于传输一些额外的字段，但可能会被插件忽略

Example configurations

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "type": "bridge",
  // type (plugin) specific
  "bridge": "cni0",
  "ipam": {
    "type": "host-local",
    // ipam specific
    "subnet": "10.1.0.0/16",
    "gateway": "10.1.0.1"
  },
  "dns": {
    "nameservers": [ "10.1.0.1" ]
  }
}

　　

{
  "cniVersion": "0.3.1",
  "name": "pci",
  "type": "ovs",
  // type (plugin) specific
  "bridge": "ovs0",
  "vxlanID": 42,
  "ipam": {
    "type": "dhcp",
    "routes": [ { "dst": "10.3.0.0/16" }, { "dst": "10.4.0.0/16" } ]
  }
  // args may be ignored by plugins
  "args": {
    "labels" : {
        "appVersion" : "1.0"
    }
  }
}

　　

{
  "cniVersion": "0.3.1",
  "name": "wan",
  "type": "macvlan",
  // ipam specific
  "ipam": {
    "type": "dhcp",
    "routes": [ { "dst": "10.0.0.0/8", "gw": "10.0.0.1" } ]
  },
  "dns": {
    "nameservers": [ "10.0.0.1" ]
  }
}

　　

Network Configuration Lists

Network configuration lists能够以指定顺序允许多个CNI插件，并且将每个插件的允许结果传递给下一个插件。列表中包含了一些众所周知的字段以及由一个或多个标准的CNI network configuration组成的列表（如上所示）。

列表以JSON格式描述，可以储存在磁盘中，也可以由容器运行时以其他方式产生。接下来的这些字段是众所周知的并且有对应的含义：

• cniVersion（string）：以Semantic Version 2.0描述的CNI版本，对此整个configuration list以及每个单独的configuraion必须遵从
• name （string）：Network name。这应该在整个管理域中都是唯一的
• plugins （lists）：一系列标准的CNI network configuration dictionary （如上所示）

当执行插件列表时，运行时必须用列表的name和cniVersion字段替代每个network configuraion的name和cniVersion字段。这确保了列表中插件的name和CNI版本都是一致的，从而避免插件之间产生版本冲突。如果插件通过network configuration的capability字段说明它支持某种specific capability，那么运行时必须将capability-based keys以map的形式插入插件的config JSON的runtimeConfig字段中。同时，传给runtimeConfig的key必须和network configuration的capabilities key的名字相同。

对于ADD操作，运行时必须添加一个prevResult字段到下一个插件的configuration JSON中，并且它的内容就是上一个插件的以JSON格式描述的结果。并且每个插件都必须将preResult的内容输出到stdout从而让后续的插件或者运行时可以获取该结果，除非，它们想要修改或限制之前的结果。插件是允许修改或限制全部或者部分的prevResult内容的。然而对于支持包含prevResult的CNI版本的插件，它必须显式地通过，修改或者限制prevResult，但是忽略该字段是不允许的。

同时，运行时必须在同一环境下执行列表中的每个插件

对于DEL操作，运行时必须以相反的顺序执行插件列表

Network Configuration List Error Handling

当在执行插件列表时发生了错误，那么运行时必须停止执行。如果ADD操作执行失败了，当运行时要处理错误时，它需要以和ADD相反的顺序对列表中的插件执行DEL操作，即使其中某些插件在ADD操作中还为被调用。

插件必须完整地执行DEL操作并不报错，即使有些资源缺失了。比如，对于IPAM插件，即使container network namespace 已经不存在了，它仍然会释放IP allocation并且成功返回，除非network namespace对于IPAM特别重要。尽管DHCP会向container network interface发送一个'release' message，但是因为DHCP leases都是有生命周期的，因此release操作并没有那么重要，也就不应该返回错误。另外，对于bridge插件即使container network namespace和/或者container network interface已经不存在了，它也要调用IPAM插件的DEL操作并且删除相应的资源（如果有的话）。

Example network configuration lists

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "plugins": [
    {
      "type": "bridge",
      // type (plugin) specific
      "bridge": "cni0",
      // args may be ignored by plugins
      "args": {
        "labels" : {
            "appVersion" : "1.0"
        }
      },
      "ipam": {
        "type": "host-local",
        // ipam specific
        "subnet": "10.1.0.0/16",
        "gateway": "10.1.0.1"
      },
      "dns": {
        "nameservers": [ "10.1.0.1" ]
      }
    },
    {
      "type": "tuning",
      "sysctl": {
        "net.core.somaxconn": "500"
      }
    }
  ]
}

　　

Network configuration list runtime examples

基于上述的network configuraion list，容器运行时需要执行以下步骤来完成ADD操作。需要注意的是，运行时会将configuration list中的cniVersion和name字段添加到每个插件的configuration中，从而保证列表中所有插件的版本和名字一致。

1、首先以如下格式调用bridge插件

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "type": "bridge",
  "bridge": "cni0",
  "args": {
    "labels" : {
        "appVersion" : "1.0"
    }
  },
  "ipam": {
    "type": "host-local",
    // ipam specific
    "subnet": "10.1.0.0/16",
    "gateway": "10.1.0.1"
  },
  "dns": {
    "nameservers": [ "10.1.0.1" ]
  }
}

　　

2、接着以如下的JSON调用tuning插件，其中的prevResult字段包含了bridge插件返回的结果

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "type": "tuning",
  "sysctl": {
    "net.core.somaxconn": "500"
  },
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 0
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}

　　

给定同样的network configuraion list，容器运行时会以如下步骤完成DEL操作。需要注意的是，并不需要prevResult字段，因为DEL操作并不返回任何result。另外，插件的执行顺序和ADD是相反的。

1、首先以如下JSON调用tuning插件

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "type": "tuning",
  "sysctl": {
    "net.core.somaxconn": "500"
  }
}

　　

2、接着以如下JSON调用bridge插件

{
  "cniVersion": "0.3.1",
  "name": "dbnet",
  "type": "bridge",
  "bridge": "cni0",
  "args": {
    "labels" : {
        "appVersion" : "1.0"
    }
  },
  "ipam": {
    "type": "host-local",
    // ipam specific
    "subnet": "10.1.0.0/16",
    "gateway": "10.1.0.1"
  },
  "dns": {
    "nameservers": [ "10.1.0.1" ]
  }
}

　　

IP Allocation

作为整个操作的一部分，CNI插件需要给interface分配并维护一个IP地址，并且还要安装一些和该interface有关的必要的路由。这给了CNI插件很大的灵活性同时也给它造成了很大的负担。许多插件需要重复编写多种用户想要的IP管理框架（例如，dhcp, host-local）。为了减轻各个插件的负担，并且将IP管理的功能独立出来，我们定义了第二种插件类型 -- IP Address Management 插件（IPAM插件）。此时，其他插件的任务就是在适当的执行过程中调用相应的IPAM插件。IPAM插件用于确定interface的IP/子网，网关，路由并且将这些信息返回"main" plugin去执行。IPAM插件可以从一个协议（如dhcp）中，或者从本地文件系统存储的数据中，或者network configuration file中的"ipam"字段，或者上述这些方式的组合中获取信息。

IP Address Management (IPAM) Interface

和CNI插件类似，IPAM插件也是以运行可执行文件的方式被调用的。可执行文件将会在一些预先定义的路径列表中查找，通过CNI_PATH指定。IPAM插件将获得所有传输给CNI插件的环境变量，并且和CNI插件一样，IPAM通过stdin获取network configuration

对于ADD命令，如果返回值为0，并且stdout中有如下的JSON格式，说明执行成功

{
  "cniVersion": "0.3.1",
  "ips": [
      {
          "version": "<4-or-6>",
          "address": "<ip-and-prefix-in-CIDR>",
          "gateway": "<ip-address-of-the-gateway>"  (optional)
      },
      ...
  ],
  "routes": [                                       (optional)
      {
          "dst": "<ip-and-prefix-in-cidr>",
          "gw": "<ip-of-next-hop>"                  (optional)
      },
      ...
  ]
  "dns": {
    "nameservers": <list-of-nameservers>            (optional)
    "domain": <name-of-local-domain>                (optional)
    "search": <list-of-search-domains>              (optional)
    "options": <list-of-options>                    (optional)
  }
}

　　

与常规的CNI插件不同的是，IPAM插件返回的是简化的Result结构，其中不包括interfaces字段，因为IPAM插件不应该关注它们的父插件配置的interfaces，那些有特殊要求的IPAM插件除外（例如，dhcp IPAM插件）。

ips字段包含了一系列的IP配置信息，详情参见IP well-known structure

dns字段包含了一个由通用的DNS信息组成的字典。详情参见DNS well-known structure

返回的Errors和logs的和CNI插件相同。详情参见CNI Plugin Result

IPAM插件的例子如下：

• host-local：在一个特定的范围内选择一个未被其他container使用的IP
• dhcp：使用DHCP协议获取并且维护一个IP的租用。DHCP request会通过刚创建的container interface发送出来，因此相关的network必须支持广播

Notes：

• 路由应该被配置为0 metric
• 默认路由应该配置为"0.0.0.0/0"。因为其他的network可能已经配置了默认路由，CNI插件必须能够跳过已有的默认配置

Well-known Structures

IPs：

  "ips": [
      {
          "version": "<4-or-6>",
          "address": "<ip-and-prefix-in-CIDR>",
          "gateway": "<ip-address-of-the-gateway>",      (optional)
          "interface": <numeric index into 'interfaces' list> (not required for IPAM plugins)
      },
      ...
  ]

　　

ips字段是一个由插件决定的IP配置列表。每个条目都是都是一个dictionary，描述了一个network interface的IP配置。多个network interface的IP配置和单个interface上的多个IP配置都将以ips列表中的不同条目返回。插件已知的所有特性都要提供，即使并不是严格必须的：

• version （string）："4"或者"6"，代表了条目中IP地址的版本。所有的IP地址和网关地址都要符合相应的版本
• address （string）：CIDR形式的IP地址（例如，"192.168.1.3/24"）
• gateway （string）：对应子网的默认网关，如果存在的话。并不要求CNI插件添加任何与网关相关的路由。路由是单独通过routes字段指定的。一个使用该字段的例子是，CNI bridge插件将该地址添加到Linux bridge中，将其作为网关。
• interface （uint）：该值表示，此IP配置需要作用的interface，在返回的结果JSON中的interfaces字段中对应的下标。IPAM插件不能返回这个值，因为它们没有任何关于network interface的信息

Routes：

  "routes": [
      {
          "dst": "<ip-and-prefix-in-cidr>",
          "gw": "<ip-of-next-hop>"               (optional)
      },
      ...
  ]

　　

每个routes字段由以下内容组成。所有的IP地址在routes中一定要有相同的IP版本，4或者6

• dst （string）：以CIDR描述的目标子网
• gw （string）：网关的IP地址。如果该字段不存在，则假设为默认网关（由CNI插件决定）

DNS：

  "dns": {
    "nameservers": <list-of-nameservers>                 (optional)
    "domain": <name-of-local-domain>                     (optional)
    "search": <list-of-additional-search-domains>        (optional)
    "options": <list-of-options>                         (optional)
  }

　　

dns字段包含了由一些通用的DNS信息组成的dictionary

• nameservers （list of strings）：一系列对network可见的，以优先级顺序排列的DNS nameserver列表。列表中的每一项都包含了一个IPv4或者一个IPv6地址
• domain （string）：用于查找short hostname的本地域
• search （list of strings）：以优先级顺序排列的用于查找short domain的查找域。对于大多数resolver，它的优先级比domain更高
• options （list of strings）：一系列可以被传输给resolver的可选项

Well-known Error Codes

• 1 - CNI版本不兼容
• 2 - network configuration存在不支持的字段。错误信息中必须包含不支持字段的key和value