CNI规范 0.4.0-dev 翻译版

2018-10-29  本文已影响0人  一个大大大坑

容器网络接口规范

翻阅历史记录，发现此篇未发布翻译稿，截止目前 CNI SPEC 版本已经至 0.4.0. 了。

版本

这是CNI 规范版本0.4.0-dev。此规范包含未发布的更改。

请注意，这与此存储库中的CNI库和插件的版本无关（例如，版本的发布版本）。

发布版本

已发布的规范版本可作为Git标签使用。

标签 规范永久链接 主要变化
spec-v0.3.1 规范v0.3.1 无（仅限拼写错误）
spec-v0.3.0 规格v0.3.0 丰富的结果类型，插件链接
spec-v0.2.0 规范v0.2.0 VERSION命令
spec-v0.1.0 规格v0.1.0 初始版本

不要依赖这些标签稳定。在将来，我们可能会改变我们的想法，即哪个特定提交是给定历史规范版本的正确标记。

概观

本文档提出了一种基于插件的通用网络解决方案，适用于Linux，容器网络接口或CNI上的应用程序容器。它是从衍生RKT网络的议案，旨在满足众多的设计考虑在网络RKT。

出于本提案的目的，我们非常具体地定义了两个术语：

本文档旨在指定“运行时”和“插件”之间的接口。虽然存在某些众所周知的字段，但运行时可能希望将附加信息传递给插件。这些扩展不是本规范的一部分，但记录为约定。关键词“必须”，“不得”，“必须”，“应”，“不得”，“应该”，“不应该”，“推荐”，“可以”和“可选”的使用如RFC 2119。

一般考虑

CNI插件

概观

每个CNI插件必须实现为容器管理系统调用的可执行文件（例如rkt或Kubernetes）。

CNI插件负责将网络接口插入容器网络命名空间（例如，veth对的一端）并在主机上进行任何必要的更改（例如，将veth的另一端连接到桥中）。然后，它应该通过调用适当的IPAM插件将IP分配给接口并设置与IP地址管理部分一致的路由。

参数

CNI插件必须支持的操作是：

运行时必须使用网络类型（请参阅下面的网络配置）作为要调用的可执行文件的名称。然后，运行时应在预定义目录列表中查找此可执行文件（此规范未规定目录列表）。一旦找到，它必须使用以下环境变量调用可执行文件以进行参数传递：

必须通过stdin将JSON格式的网络配置流式传输到插件。这意味着它不依赖于磁盘上的特定文件，并且可能包含在调用之间更改的信息。

结果

请注意，IPAM插件应返回IP分配中Result所述的缩写结构。

插件必须指示成功，返回代码为零，并且在ADD命令的情况下，将以下JSON打印到stdout。在ips和dns项目应该是相同的输出由IPAM插件（见返回IP分配的详细信息）除了插件应该在填写interface适当的指标，这是从IPAM插件输出丢失，因为IPAM插件应该是不知道的接口。

{
  "cniVersion": "0.4.0",
  "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": {                                                   (optional)
    "nameservers": <list-of-nameservers>                     (optional)
    "domain": <name-of-local-domain>                         (optional)
    "search": <list-of-additional-search-domains>            (optional)
    "options": <list-of-options>                             (optional)
  }
}

cniVersion指定插件使用的CNI规范的语义版本2.0。插件可能支持多个CNI规范版本（因为它通过VERSION命令报告），此处cniVersion插件返回的结果必须与网络配置中cniVersion指定的一致。如果插件不支持网络配置，则插件应返回错误代码1（有关详细信息，请参阅众所周知的错误代码）。cniVersion

interfaces描述了插件创建的特定网络接口。如果CNI_IFNAME变量存在，则插件必须使用该名称作为沙箱/管理程序接口，否则返回错误。

该ips字段是IP配置信息的列表。有关更多信息，请参阅IP知名结构部分。

该dns字段包含由常见DNS信息组成的字典。有关更多信息，请参阅DNS知名结构部分。

该规范未声明CNI消费者必须如何处理此信息。示例包括生成/etc/resolv.conf要注入容器文件系统的文件或在主机上运行DNS转发器。

错误必须由非零返回码表示，并且以下JSON将打印到stdout：

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

cniVersion指定插件使用的CNI规范的语义版本2.0。错误代码0-99保留用于众所周知的错误（参见“已知错误代码”部分）。100+的值可以自由地用于插件特定错误。

此外，stderr可用于非结构化输出，例如日志。

网络配置

网络配置以JSON格式描述。配置可以存储在磁盘上，也可以由容器运行时从其他源生成。以下字段是众所周知的，具有以下含义：

插件可以定义它们接受的其他字段，如果使用未知字段调用，则可能会生成错误。例外情况是该args字段可用于传递任意数据，如果不理解，应该被插件忽略。

示例配置

{
  "cniVersion": "0.4.0",
  "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.4.0",
  "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.4.0 ”，
   “ 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 “ ]
  }
}

网络配置列表

网络配置列表提供了一种机制，可以按照定义的顺序为单个容器运行多个CNI插件，并将每个插件的结果传递给下一个插件。该列表由众所周知的字段和一个或多个标准CNI网络配置列表组成（见上文）。

该列表以JSON格式描述，可以存储在磁盘上，也可以由容器运行时从其他源生成。以下字段是众所周知的，具有以下含义：

执行插件列表时，运行时必须使用列表本身的name和cniVersion字段替换列表中每个单独网络配置中的name和cniVersion字段。这可确保列表中所有插件执行的名称和CNI版本相同，从而防止插件之间的版本控制冲突。runtimeConfig如果插件通过capabilities其网络配置的密钥通告它支持特定功能，则运行时还可以将基于功能的密钥作为插件的配置JSON 的顶级密钥中的映射传递。传递的密钥runtimeConfig必须与capabilities插件网络配置的密钥匹配特定功能的名称。有关功能以及如何通过以下方式将其发送到插件的详细信息，请参阅CONVENTIONS.mdruntimeConfig 键。

对于ADD操作，运行时还必须prevResult在第一个插件之后的任何插件的配置JSON中添加一个字段，该插件必须是ResultJSON格式的前一个插件（如果有）的插件（见下文）。对于CHECK和DEL动作，运行时必须（除非它可能被省略，DEL如果不可用）prevResult向每个插件的配置JSON 添加一个字段，该字段必须是JSON格式的Result前一个ADD动作（见下文）。对于ADD动作，插件应该回应内容prevResult字段到它们的stdout以允许后续插件（和运行时）接收结果，除非他们希望修改或抑制先前的结果。允许插件修改或抑制全部或部分内容prevResult。但是，支持包含该prevResult字段的CNI规范版本的插件必须prevResult通过传递，修改或明确禁止它来处理。违反此规范是不了解该prevResult领域的。

运行时还必须使用相同的环境执行列表中的每个插件。

对于DEL操作，运行时必须以反向顺序执行插件。

网络配置列表错误处理

当在插件列表上执行操作时发生错误（例如，ADD或者DEL），运行时必须停止执行列表。

如果ADD操作失败，当运行时决定处理失败时，它应该对列表中的所有插件执行DEL操作（ADD与上面指定的相反的顺序），即使在ADD操作期间未调用某些插件也是如此。

DEL即使缺少某些资源，插件通常也应该完成一个没有错误的操作。例如，即使容器网络命名空间不再存在，IPAM插件通常也应该释放IP分配并返回成功，除非该网络命名空间对于IPAM管理至关重要。虽然DHCP通常可以在容器网络接口上发送“释放”消息，但由于DHCP租约具有生命周期，因此该释放操作不会被视为关键，并且不应返回错误。再举一个例子，bridge即使容器网络命名空间和/或容器网络接口不再存在，插件也应该将DEL操作委托给IPAM插件并清理自己的资源（如果存在）。

示例网络配置列表

{
  "cniVersion": "0.4.0",
  "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"
      }
    }
  ]
}

网络配置列表运行时示例

给定上面显示的网络配置列表JSON ，容器运行时将为该ADD操作执行以下步骤。请注意，运行时将配置列表中的cniVersion和name字段添加到传递给每个插件的配置JSON，以确保列表中所有插件的版本控制和名称一致。

  1. 首先bridge使用以下JSON 调用该插件：
{
   “ cniVersion ”：“ 0.4.0 ”，
   “ 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 “ ] 
  } 
}
  1. 接下来tuning使用以下JSON 调用插件，包括prevResult包含bridge插件的JSON响应的字段：
{
  "cniVersion": "0.4.0",
  "name": "dbnet",
  "type": "tuning",
  "sysctl": {
    "net.core.somaxconn": "500"
  },
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 2
        }
    ],
    "interfaces": [
        {
            "name": "cni0",
            "mac": "00:11:22:33:44:55",
        },
        {
            "name": "veth3243",
            "mac": "55:44:33:22:11:11",
        },
        {
            "name": "eth0",
            "mac": "99:88:77:66:55:44",
            "sandbox": "/var/run/netns/blue",
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}

给定相同的网络配置JSON列表，容器运行时将为该CHECK操作执行以下步骤。

  1. 首先bridge使用以下JSON 调用插件，包括prevResult包含操作的JSON响应的字段ADD：
{
  "cniVersion": "0.4.0",
  "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" ]
  }
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 2
        }
    ],
    "interfaces": [
        {
            "name": "cni0",
            "mac": "00:11:22:33:44:55",
        },
        {
            "name": "veth3243",
            "mac": "55:44:33:22:11:11",
        },
        {
            "name": "eth0",
            "mac": "99:88:77:66:55:44",
            "sandbox": "/var/run/netns/blue",
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}
  1. 接下来tuning使用以下JSON 调用插件，包括prevResult包含操作的JSON响应的字段ADD：
{
  "cniVersion": "0.4.0",
  "name": "dbnet",
  "type": "tuning",
  "sysctl": {
    "net.core.somaxconn": "500"
  },
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 2
        }
    ],
    "interfaces": [
        {
            "name": "cni0",
            "mac": "00:11:22:33:44:55",
        },
        {
            "name": "veth3243",
            "mac": "55:44:33:22:11:11",
        },
        {
            "name": "eth0",
            "mac": "99:88:77:66:55:44",
            "sandbox": "/var/run/netns/blue",
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}

给定相同的网络配置JSON列表，容器运行时将为该DEL操作执行以下步骤。请注意，插件的执行顺序与ADD和CHECK动作相反。

  1. 首先tuning使用以下JSON 调用插件，包括prevResult包含操作的JSON响应的字段ADD：
{
  "cniVersion": "0.4.0",
  "name": "dbnet",
  "type": "tuning",
  "sysctl": {
    "net.core.somaxconn": "500"
  },
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 2
        }
    ],
    "interfaces": [
        {
            "name": "cni0",
            "mac": "00:11:22:33:44:55",
        },
        {
            "name": "veth3243",
            "mac": "55:44:33:22:11:11",
        },
        {
            "name": "eth0",
            "mac": "99:88:77:66:55:44",
            "sandbox": "/var/run/netns/blue",
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}
  1. 接下来bridge使用以下JSON 调用插件，包括prevResult包含来自ADD操作的JSON响应的字段：
{
  "cniVersion": "0.4.0",
  "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" ]
  },
  "prevResult": {
    "ips": [
        {
          "version": "4",
          "address": "10.0.0.5/32",
          "interface": 2
        }
    ],
    "interfaces": [
        {
            "name": "cni0",
            "mac": "00:11:22:33:44:55",
        },
        {
            "name": "veth3243",
            "mac": "55:44:33:22:11:11",
        },
        {
            "name": "eth0",
            "mac": "99:88:77:66:55:44",
            "sandbox": "/var/run/netns/blue",
        }
    ],
    "dns": {
      "nameservers": [ "10.1.0.1" ]
    }
  }
}

IP分配

作为其操作的一部分，期望CNI插件为接口分配（和维护）IP地址并安装与该接口相关的任何必要路由。这为CNI插件提供了极大的灵活性，但也给它带来了很大的负担。许多CNI插件需要具有相同的代码才能支持用户可能需要的几种IP管理方案（例如dhcp，host-local）。

为了减轻负担并使IP管理策略与CNI插件的类型正交，我们定义了第二种类型的插件 - IP地址管理插件（IPAM插件）。然而，CNI插件的责任是在其执行的适当时刻调用IPAM插件。IPAM插件必须确定接口IP /子网，网关和路由，并将此信息返回到“主”插件以应用。IPAM插件可以通过协议（例如dhcp），存储在本地文件系统上的数据，网络配置文件的“ipam”部分或上述的组合来获得信息。

IP地址管理（IPAM）接口

与CNI插件一样，通过运行可执行文件来调用IPAM插件。在预定义的路径列表中搜索可执行文件，通过CNI插件指示CNI_PATH。IPAM插件必须接收传递给CNI插件的所有相同环境变量。就像CNI插件一样，IPAM插件通过stdin接收网络配置。

必须通过零返回代码指示成功，并将以下JSON打印到stdout（在ADD命令的情况下）：

{
  "cniVersion": "0.4.0",
  "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": {                                          (optional)
    "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插件应该不知道由其父插件配置的接口，除了IPAM特别需要的接口（例如，像dhcpIPAM插件）。

cniVersion指定IPAM插件使用的CNI规范的语义版本2.0。IPAM插件可能支持多个CNI规范版本（因为它通过VERSION命令报告），此处cniVersion结果中IPAM插件返回的内容必须与网络配置中cniVersion指定的一致。如果IPAM插件不支持网络配置，则插件应返回错误代码1（有关详细信息，请参阅众所周知的错误代码）。cniVersion

该ips字段是IP配置信息的列表。有关更多信息，请参阅IP知名结构部分。

该dns字段包含由常见DNS信息组成的字典。有关更多信息，请参阅DNS知名结构部分。

错误和日志的传达方式与CNI插件相同。有关详细信息，请参阅CNI插件结果部分。

IPAM插件示例：

笔记

着名的结构

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配置信息的列表。每个项目都是描述网络接口的IP配置的字典。多个网络接口的IP配置和单个接口的多个IP配置可以作为ips列表中的单独项目返回。即使没有严格要求，也应提供插件已知的所有属性。

Routes

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

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信息组成的字典。

众所周知的错误代码

除此处指定外，不得使用错误代码1-99。

上一篇 下一篇

猜你喜欢

热点阅读