Kubernetes Network Custom Resource Definition De-facto Standard
1. Goals
本文檔提出了將Kubernetes pod連接到一個(gè)或多個(gè)邏輯或物理網(wǎng)絡(luò)的要求和過(guò)程的規(guī)范，包括使用容器網(wǎng)絡(luò)接口（CNI）連接pod網(wǎng)絡(luò)的插件的要求。
1.1 Non-Goals of Version 1
出于簡(jiǎn)化和/或需要達(dá)成一些合理的共識(shí)，本文件特別沒(méi)有涉及某些問(wèn)題。 這些問(wèn)題可能會(huì)在本規(guī)范的未來(lái)版本中得到解決。
1.1.1 Scheduling and resource management
在資源管理工作組中正在努力整合調(diào)度和資源管理（例如，確保節(jié)點(diǎn)沒(méi)有分配比可用網(wǎng)絡(luò)資源更多的pod），其中涉及該工作組和SIG網(wǎng)絡(luò)的各個(gè)成員。
本規(guī)范的未來(lái)版本可能包含資源管理的各個(gè)方面。
1.1.2 對(duì)Kubernetes API的更改
此規(guī)范明確避免了對(duì)現(xiàn)有Kubernetes API的更改。
這些變化需要更長(zhǎng)的上游流程，但希望通過(guò)證明概念并提供多個(gè)pod網(wǎng)絡(luò)附件的一個(gè)或多個(gè)實(shí)際實(shí)現(xiàn)，
該文檔可以作為未來(lái)這些變化的基礎(chǔ)。
1.1.3 Interaction with the Kubernetes API
未指定其他pod網(wǎng)絡(luò)附件與Kubernetes API及其對(duì)象（如服務(wù)Services，端點(diǎn)Endpoints，代理proxies等）的交互。
SIG網(wǎng)絡(luò)在2017年7月/ 8月詳細(xì)討論了該主題，并決定需要更改Kubernetes API，這是該規(guī)范的明確非目標(biāo)。
1.1.4 Changes to the Kubernetes CNI Driver
為確保輕松使用此規(guī)范及其實(shí)現(xiàn)，Kubernetes CNI驅(qū)動(dòng)程序不需要進(jìn)行任何更改（例如pkg / kubelet / dockershim / network / cni / *）。
已經(jīng)提出了對(duì)驅(qū)動(dòng)程序的更改以支持多個(gè)pod網(wǎng)絡(luò)附件，并且已經(jīng)編寫(xiě)了多個(gè)概念驗(yàn)證，但是對(duì)于多個(gè)附件應(yīng)該如何工作以及因此CNI驅(qū)動(dòng)程序中需要進(jìn)行哪些更改尚未達(dá)成上游共識(shí)。
1.1.5 Enabling Implementations That Are Not CNI Plugins(啟用不是CNI插件的實(shí)現(xiàn))
此規(guī)范僅嘗試啟用Kubernetes網(wǎng)絡(luò)插件，該插件使用像dockershim，CRI-O和rkt這樣的Kubernetes運(yùn)行時(shí)的CNI驅(qū)動(dòng)程序。 該規(guī)范期望通過(guò)實(shí)現(xiàn)來(lái)引導(dǎo)pod網(wǎng)絡(luò)附件操作，該實(shí)現(xiàn)需要是CNI插件。 該規(guī)范的未來(lái)版本可能會(huì)重新審視此要求。
2. Definitions
2.1 Implementation
實(shí)現(xiàn)此規(guī)范的Kubernetes網(wǎng)絡(luò)插件;
從Kubernetes 1.11開(kāi)始，這被定義為符合容器網(wǎng)絡(luò)接口（CNI）規(guī)范v0.1.0或更高版本的插件。
應(yīng)該將Kubernetes配置為調(diào)用所有pod網(wǎng)絡(luò)操作的實(shí)現(xiàn)，然后實(shí)現(xiàn)根據(jù)pod的注釋和本規(guī)范中定義的Custom Resources確定要執(zhí)行的其他操作。
2.2 Kubernetes Cluster-Wide Default Network
根據(jù)Kubernetes的當(dāng)前行為和要求連接所有pod的網(wǎng)絡(luò)。
2.3 Network Attachment(Network Attachment)
允許pod直接與給定邏輯或物理網(wǎng)絡(luò)通信的方法。
通常（但不一定）每個(gè)附件采用放置在pod的網(wǎng)絡(luò)命名空間中的內(nèi)核網(wǎng)絡(luò)接口的形式。
每個(gè)附件可能導(dǎo)致分配給pod的零個(gè)或多個(gè)IP地址。
2.4 CNI Delegating Plugin
符合本規(guī)范的實(shí)現(xiàn)，它將pod網(wǎng)絡(luò)附件/分離操作委托給符合CNI規(guī)范的其他插件。 例子包括Multus和CNI-Genie。
此規(guī)范將CNI Delegating Plugin的特定要求和建議置于標(biāo)記為此類(lèi)的部分下。
如果實(shí)現(xiàn)不是CNI委托插件，則可以忽略這些標(biāo)記部分及其任何子部分中的要求和建議。
3. NetworkAttachmentDefinition Object
此規(guī)范定義NetworkAttachmentDefinition自定義資源對(duì)象，該對(duì)象描述如何將pod連接到對(duì)象引用的邏輯或物理網(wǎng)絡(luò)。
3.1 Custom Resource Definition (CRD)
CRD告訴Kubernetes API如何公開(kāi)NetworkAttachmentDefinition對(duì)象。 請(qǐng)參閱下面的對(duì)象本身的定義。
apiVersion: apiextensions.k8s.io/v1beta1
kind: CustomResourceDefinition
metadata:
name: network-attachment-definitions.k8s.cni.cncf.io
spec:
group: k8s.cni.cncf.io
version: v1
scope: Namespaced
names:
plural: network-attachment-definitions
singular: network-attachment-definition
kind: NetworkAttachmentDefinition
shortNames:
- net-attach-def
validation:
openAPIV3Schema:
properties:
spec:
properties:
config:
type: string
3.2 NetworkAttachmentDefinition Object Definition
NetworkAttachmentDefinition對(duì)象本身僅包含“spec”部分。 其定義（以Go形式）應(yīng)為：
type NetworkAttachmentDefinition struct {
metav1.TypeMeta
// Note that ObjectMeta is mandatory, as an object
// name is required
metav1.ObjectMeta
// Specification describing how to add or remove network
// attachments for a Pod. In the absence of valid keys in
// the Spec field, the implementation shall attach/detach an
// implementation-known network referenced by the object’s
// name.
// +optional
Spec NetworkAttachmentDefinitionSpec `json:"spec"`
}
type NetworkAttachmentDefinitionSpec struct {
// Config contains a standard JSON-encoded CNI configuration
// or configuration list which defines the plugin chain to
// execute. The CNI configuration may omit the 'name' field
// which will be populated by the implementation when the
// Config is passed to CNI delegate plugins.
// +optional
Config string `json:"config,omitempty"`
}
3.2.1 YAML Example: CNI config JSON in object
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: a-bridge-network
spec:
config: '{
"cniVersion": "0.3.0",
"name": "a-bridge-network",
"type": "bridge",
"bridge": "br0",
"isGateway": true,
"ipam": {
"type": "host-local",
"subnet": "192.168.5.0/24",
"dataDir": "/mnt/cluster-ipam"
}
}'
3.2.2 YAML Example: CNI configlist JSON in object
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: another-bridge-network
spec:
config: '{
"cniVersion": "0.3.0",
"name": "another-bridge-network",
"plugins": [
{
"type": "bridge",
"bridge": "br0",
"ipam": {
"type": "host-local",
"subnet": "192.168.5.0/24"
}
},
{
"type": "port-forwarding"
},
{
"type": "tuning",
"sysctl": {
"net.ipv4.conf.all.log_martians": "1"
}
}
]
}'
3.2.3 YAML Example: Limited CNI config required ("thick" plugin)
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: a-bridge-network
spec:
config: '{
"cniVersion": "0.3.0",
"type": "awesome-plugin"
}'
3.2.4 YAML Example: Implementation-specific Network Reference
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: a-bridge-network
3.3 NetworkAttachmentDefinition Object Naming Rules
根據(jù)Kubernetes驗(yàn)證命名空間名稱(chēng)的方式，有效的NetworkAttachmentDefinition對(duì)象名稱(chēng)必須由DNS-1123標(biāo)簽格式的單元組成。 建議每個(gè)DNS-1123標(biāo)簽單元不超過(guò)63個(gè)字符。
“DNS-1123標(biāo)簽必須由小寫(xiě)字母數(shù)字字符或' - '組成，并且必須以字母數(shù)字字符開(kāi)頭和結(jié)尾”
Kubernetes錯(cuò)誤消息
可以通過(guò)匹配此正則表達(dá)式來(lái)驗(yàn)證標(biāo)簽：
[a-z0-9]([-a-z0-9]*[a-z0-9])?
3.3.1 Examples
example-namespace/attachment-name
attachment-name
3.4 CNI Delegating Plugin Requirements
對(duì)于CNI委托插件的實(shí)現(xiàn)，該實(shí)現(xiàn)將實(shí)際的附件/分離“委托”給一個(gè)或多個(gè)附加的CNI插件。 NetworkAttachmentDefinition對(duì)象包含確定要執(zhí)行哪些CNI插件以及傳遞給它們的選項(xiàng)的必要信息。
3.4.1 Determining CNI Plugins for a NetworkAttachmentDefinition Object
CNI委托插件必須按列出的順序使用以下規(guī)則來(lái)確定哪個(gè)CNI插件要執(zhí)行以便由NetworkAttachmentDefinition對(duì)象描述的pod對(duì)給定網(wǎng)絡(luò)的附件執(zhí)行：
- 如果NetworkAttachmentDefinition.Spec中存在“config”鍵，則鍵值的內(nèi)容用于根據(jù)CNI規(guī)范執(zhí)行插件
- 如果磁盤(pán)上存在CNI .configlist文件，其JSON“name”鍵與NetworkAttachmentDefinition對(duì)象的名稱(chēng)匹配，則會(huì)加載其內(nèi)容并用于根據(jù)CNI規(guī)范執(zhí)行插件。
- 如果磁盤(pán)上存在CNI.config文件，其JSON“name”鍵與NetworkAttachmentDefinition對(duì)象的名稱(chēng)匹配，則會(huì)加載其內(nèi)容并用于根據(jù)CNI規(guī)范執(zhí)行插件。
- 否則，網(wǎng)絡(luò)請(qǐng)求必須失敗
3.4.2 Spec.Config and the CNI JSON 'name' Field
如果Spec.Config鍵有效但其數(shù)據(jù)省略了CNI JSON'name'字段，則CNI委托插件應(yīng)在將CNI JSON配置發(fā)送到委托插件之前，將包含NetworkAttachmentDefinition對(duì)象名稱(chēng)的'name'字段添加到CNI JSON。
這旨在簡(jiǎn)化“厚”插件的配置，其中委托插件需要最少的配置。
3.4.2.1 "Name" Injection Example
給定以下NetworkAttachmentDefinition對(duì)象：
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
name: a-bridge-network
spec:
config: '{
"cniVersion": "0.3.0",
"type": "awesome-plugin"
}'
CNI委托插件將以下CNI JSON配置發(fā)送到'awesome-plugin'二進(jìn)制文件，該二進(jìn)制文件通過(guò)將NetworkAttachmentDefinition對(duì)象名稱(chēng)作為其數(shù)據(jù)注入“name”字段而生成：
{
"cniVersion": "0.3.0",
"name": "a-bridge-network",
"type": "awesome-plugin"
}
3.4.3 NetworkAttachmentDefinition Object and CNI JSON Configuration Naming Considerations
根據(jù)Kubernetes要求，每個(gè)NetworkAttachmentDefinition對(duì)象必須具有名稱(chēng)。 CNI規(guī)范強(qiáng)烈建議CNI JSON配置包含名稱(chēng)，未來(lái)的CNI規(guī)范版本將需要名稱(chēng)。
此規(guī)范強(qiáng)烈建議NetworkAttachmentDefinition對(duì)象名稱(chēng)與NetworkAttachmentDefinition對(duì)象引用的CNI JSON配置中的“name”鍵匹配（無(wú)論是存儲(chǔ)在磁盤(pán)上還是存儲(chǔ)在NetworkAttachmentDefinition.Spec.Config鍵中）。
這減少了用戶(hù)的混淆，并使NetworkAttachmentDefinition對(duì)象和CNI配置之間的映射更加清晰。
強(qiáng)烈建議使用此匹配，因?yàn)樗赡軙?huì)將Kubernetes API對(duì)象命名要求放在外部定義的資源上。
命名最終由集群管理員決定。
4. Network Attachment Selection Annotation
要選擇應(yīng)附加pod的一個(gè)或多個(gè)輔助（“sidecar”）網(wǎng)絡(luò)，此規(guī)范定義Pod對(duì)象注釋。 由于此批注選擇的附件是輔助附件，因此Kubernetes本身不知道這些網(wǎng)絡(luò)附件，并且可能無(wú)法通過(guò)標(biāo)準(zhǔn)Kubernetes API獲取有關(guān)它們的信息。
網(wǎng)絡(luò)附件選擇注釋可用于選擇群集范圍內(nèi)的默認(rèn)網(wǎng)絡(luò)的附加附件，超出所需的初始群集范圍的默認(rèn)網(wǎng)絡(luò)附件。
4.1 Annotation Name and Format
Pod對(duì)象注釋名稱(chēng)應(yīng)為“k8s.v1.cni.cncf.io/networks”。 注釋值應(yīng)以?xún)煞N可能的格式之一指定，如下所述。 本規(guī)范的實(shí)現(xiàn)必須支持這兩種格式。
請(qǐng)注意，即使注釋引用的對(duì)象是NetworkAttachmentDefinition對(duì)象，注釋的名稱(chēng)也是“k8s.v1.cni.cncf.io/networks”。 這是故意的。
4.1.1 Comma-delimited Format
此格式旨在是一種非常簡(jiǎn)單，用戶(hù)友好的格式，僅由逗號(hào)分隔的NetworkAttachmentDefinition對(duì)象引用組成。 每個(gè)對(duì)象引用的格式是（a）<NetworkAttachmentDefinition對(duì)象名稱(chēng)>以引用pod命名空間中的NetworkAttachmentDefinition對(duì)象，或（b）<NetworkAttachmentDefinition對(duì)象命名空間> / <NetworkAttachmentDefinition對(duì)象名稱(chēng)>以引用不同命名空間中的NetworkAttachmentDefinition對(duì)象。
kind: Pod
metadata:
name: my-pod
namespace: my-namespace
annotations:
k8s.v1.cni.cncf.io/networks: net-a,net-b,other-ns/net-c
4.1.2 JSON List Format
此格式允許用戶(hù)為網(wǎng)絡(luò)附件提供特定于pod的要求。
例如，如果最終處理網(wǎng)絡(luò)附件的插件支持這些選項(xiàng)，則這些選項(xiàng)可能包括特定的IP地址或MAC地址，無(wú)論是實(shí)現(xiàn)本身還是委托插件。
kind: Pod
metadata:
name: my-pod
namespace: my-namespace
annotations:
k8s.v1.cni.cncf.io/networks: |
[
{"name":"net-a"},
{
"name":"net-b",
"ips": ["1.2.3.4"],
"mac": "aa:bb:cc:dd:ee:ff"
},
{
"name":"net-c",
"namespace":"other-ns"
}
]
4.1.2.1 JSON List Format Key Definitions
為此格式的網(wǎng)絡(luò)列表中的每個(gè)網(wǎng)絡(luò)附件映射定義以下鍵。 保留所有不包含句點(diǎn)字符的鍵名稱(chēng)，以確保將來(lái)可以擴(kuò)展此規(guī)范。 寫(xiě)入除本規(guī)范中定義的密鑰之外的密鑰的實(shí)現(xiàn)必須使用反向域名表示法（例如“org.foo.bar.key-name”）來(lái)命名非標(biāo)準(zhǔn)密鑰。
4.1.2.1.1 "name"
帶有string類(lèi)型值的必需鍵是NetworkAttachmentDefinition對(duì)象的名稱(chēng)，可以是Pod的命名空間（如果“namespace”鍵缺失或?yàn)榭眨部梢允恰皀amespace”鍵指定的另一個(gè)命名空間。
4.1.2.1.2 "namespace"
這個(gè)值為string類(lèi)型的可選鍵是由“name”鍵命名的NetworkAttachmentDefinition對(duì)象的名稱(chēng)空間。
4.1.2.1.3 "ips"
這個(gè)值為string-array的可選鍵需要處理此網(wǎng)絡(luò)附件的插件將給定的IP地址分配給pod。 此鍵的值必須至少包含一個(gè)數(shù)組元素，并且每個(gè)元素必須是有效的IPv4或IPv6地址。 如果該值無(wú)效，則網(wǎng)絡(luò)附件選擇注釋?xiě)?yīng)無(wú)效并由實(shí)現(xiàn)忽略。
4.1.2.1.3.1 "ips" Example
annotations:
k8s.v1.cni.cncf.io/networks: |
[
{
"name":"net-b",
"ips": ["10.2.2.42", "2001:db8::5"]
}
]
4.1.2.1.3.2 CNI Delegating Plugin Requirements
CNI委托插件必須向CNI“args”映射添加“ips”鍵，并將其值設(shè)置為符合“ips”鍵值的“ips”鍵值的轉(zhuǎn)換，如CNI的CONVENTIONS.md中所述。 由于該規(guī)范要求實(shí)現(xiàn)遵循“ips”，但插件可能會(huì)忽略CNI“args”，因此實(shí)現(xiàn)必須確保在返回的CNI請(qǐng)求結(jié)構(gòu)中將所請(qǐng)求的IP地址分配給網(wǎng)絡(luò)附件的接口; 如果尚未分配，則實(shí)施必須使網(wǎng)絡(luò)附件失敗。
鑒于緊接在前的網(wǎng)絡(luò)附件選擇注釋示例，CNI委托插件會(huì)將數(shù)據(jù)轉(zhuǎn)換為以下CNI JSON配置片段，該片段在“net-b”的CNI調(diào)用中傳遞給每個(gè)插件：
{
…
"args":{
"cni":{
"ips": ["10.2.2.42", "2001:db8::5"]
}
}
…
}
4.1.2.1.4 "mac"
具有值類(lèi)型字符串的此可選鍵需要處理此網(wǎng)絡(luò)附件的插件將給定的MAC地址分配給pod。 此密鑰的值必須包含有效的6字節(jié)以太網(wǎng)MAC地址或有效的20字節(jié)IP-over-InfiniBand硬件地址（如RFC4391第9.1.1節(jié)中所述）。 如果該值無(wú)效，則網(wǎng)絡(luò)附件選擇注釋?xiě)?yīng)無(wú)效并由實(shí)現(xiàn)忽略。
4.1.2.1.4.1 "mac" Example
annotations:
k8s.v1.cni.cncf.io/networks: |
[
{
"name":"net-b",
"mac": "02:23:45:67:89:01"
}
]
4.1.2.1.4.2 CNI Delegating Plugin Requirements
實(shí)現(xiàn)必須向CNI“args”映射添加“mac”密鑰（如CNI的CONVENTIONS.md中所述），并將其值設(shè)置為“mac”密鑰值的轉(zhuǎn)換。 由于此規(guī)范要求實(shí)現(xiàn)遵守“mac”，但插件可能會(huì)忽略CNI“args”，因此實(shí)現(xiàn)必須確保在返回的CNI請(qǐng)求結(jié)構(gòu)中將請(qǐng)求的MAC地址分配給網(wǎng)絡(luò)附件的接口; 如果尚未分配，則實(shí)施必須使網(wǎng)絡(luò)附件失敗。
鑒于緊接在前的網(wǎng)絡(luò)附件選擇注釋示例，CNI委托插件會(huì)將數(shù)據(jù)轉(zhuǎn)換為以下CNI JSON配置片段，該片段在“net-b”的CNI調(diào)用中傳遞給每個(gè)插件：
{
…
"args":{
"cni":{
"mac": "02:23:45:67:89:01"
}
}
…
}
4.1.2.1.5 "interface"
此值為string類(lèi)型的可選鍵要求實(shí)現(xiàn)使用此網(wǎng)絡(luò)附件生成的pod接口的給定名稱(chēng)。 此鍵的值必須是有效的Linux內(nèi)核接口名稱(chēng)。 如果該值無(wú)效，則網(wǎng)絡(luò)附件選擇注釋?xiě)?yīng)無(wú)效并由實(shí)現(xiàn)忽略。
如果先前的網(wǎng)絡(luò)附件已使用所請(qǐng)求的接口名稱(chēng)，則實(shí)施必須使當(dāng)前網(wǎng)絡(luò)附件失敗。
4.1.2.1.5.1 CNI Delegating Plugin Requirements
“接口”鍵需要CNI委托插件在調(diào)用此網(wǎng)絡(luò)附件的CNI插件時(shí)將CNI_IFNAME環(huán)境變量設(shè)置為給定值。
4.2 Multiple Attachments to the Same Network
Pod可以通過(guò)網(wǎng)絡(luò)附件選擇注釋多次請(qǐng)求連接到同一網(wǎng)絡(luò)。 這些請(qǐng)求中的每一個(gè)都被視為單獨(dú)的附件，必須由實(shí)現(xiàn)作為單獨(dú)的操作進(jìn)行處理，并且必須生成單獨(dú)的“網(wǎng)絡(luò)附件狀態(tài)注釋”條目。
4.2.1 CNI Delegating Plugin Requirements
網(wǎng)絡(luò)附件選擇注釋中的每個(gè)網(wǎng)絡(luò)引用對(duì)應(yīng)于NetworkAttachmentDefinition對(duì)象描述的CNI插件/配置列表調(diào)用。 由于CNI規(guī)范將網(wǎng)絡(luò)附件定義為[容器ID，網(wǎng)絡(luò)名稱(chēng)，CNI_IFNAME]的唯一元組，因此CNI委托插件必須確保給定網(wǎng)絡(luò)附件的所有CNI操作（例如ADD或DEL）使用相同的唯一元組， 應(yīng)該創(chuàng)建如下：
- 容器ID：由運(yùn)行時(shí)給出
- 網(wǎng)絡(luò)名稱(chēng)：存在于（或通過(guò)）NetworkAttachmentDefinition對(duì)象中
- CNI_IFNAME：如果沒(méi)有由網(wǎng)絡(luò)附件選擇注釋另外指定，由CNI委托插件為給定附件生成，并且在給定[容器ID，網(wǎng)絡(luò)名稱(chēng)]元組的所有附件中必須是唯一的。
4.2.2 Example
annotations:
k8s.v1.cni.cncf.io/networks: net-a,net-a
在此示例中，實(shí)現(xiàn)必須附加“net-a”兩次，并且每個(gè)附件將導(dǎo)致“網(wǎng)絡(luò)附件狀態(tài)注釋”列表中的單獨(dú)條目。
5. Network Attachment Status Annotation
為了確保通過(guò)Kubernetes API可以獲得網(wǎng)絡(luò)附件的結(jié)果，實(shí)現(xiàn)可以將附件操作的結(jié)果發(fā)布到請(qǐng)求附件的pod對(duì)象上的注釋。
注釋的名稱(chēng)應(yīng)為“k8s.v1.cni.cncf.io/network-status”，其值應(yīng)為JSON編碼的地圖列表。 列表中的每個(gè)元素應(yīng)該是由如下所述的網(wǎng)絡(luò)附加操作的結(jié)果組成的映射。
5.1 Source of Status Information
網(wǎng)絡(luò)附件操作的狀態(tài)圖應(yīng)包含從給定網(wǎng)絡(luò)的附件操作結(jié)果中獲取的信息。
僅在pod本身內(nèi)部有用的狀態(tài)信息（如IP路由）不需要是狀態(tài)映射的一部分，因?yàn)榇诵畔⑼ǔＥcKubernetes API客戶(hù)端無(wú)關(guān)。
5.1.1 CNI Delegating Plugin Requirements
附件的狀態(tài)應(yīng)取自CNI Result對(duì)象的第一個(gè)沙箱接口，用于該附件的CNI ADD或GET調(diào)用。 如果ADD或GET調(diào)用未返回結(jié)果（CNI規(guī)范當(dāng)前允許），則實(shí)現(xiàn)應(yīng)添加最小狀態(tài)映射，如下所述。
實(shí)現(xiàn)應(yīng)盡可能使用CNI Result對(duì)象中提供的盡可能多的信息來(lái)構(gòu)建網(wǎng)絡(luò)附件狀態(tài)注釋。 如果操作返回版本0.3.0或更高版本的CNI Result對(duì)象，則可以使用“interfaces”，“ips”和“dns”字段輕松構(gòu)建網(wǎng)絡(luò)附件狀態(tài)注釋。 如果操作返回的CNI Result對(duì)象小于0.3.0版，則實(shí)現(xiàn)應(yīng)該從CNI Result中構(gòu)建盡可能多的Network Attachment Status Annotation，并且可以填充剩余的Annotation字段（例如'interface'和'mac '）通過(guò)它希望的任何方式。
5.2 Cluster-Wide Default Network Entry
由于需要實(shí)現(xiàn)將pod連接到群集范圍的默認(rèn)網(wǎng)絡(luò)，因此即使未在“網(wǎng)絡(luò)附件選擇注釋”中指定，該網(wǎng)絡(luò)也必須在狀態(tài)映射中具有條目，并且可能沒(méi)有相應(yīng)的NetworkAttachmentDefinition對(duì)象。 該條目應(yīng)將其“默認(rèn)”鍵設(shè)置為“true”。 默認(rèn)條目可以位于狀態(tài)列表中的任何位置。
5.3 Status Map Key Definitions
為每個(gè)網(wǎng)絡(luò)附件的狀態(tài)圖定義了以下鍵。 保留所有不包含句點(diǎn)字符的鍵名稱(chēng)，以確保將來(lái)可以擴(kuò)展此規(guī)范。 寫(xiě)入除本規(guī)范中定義的密鑰之外的密鑰的實(shí)現(xiàn)必須使用反向域名表示法（例如“org.foo.bar.key-name”）來(lái)命名非標(biāo)準(zhǔn)密鑰。
5.3.1 "name"
此必需鍵的值（類(lèi)型字符串）應(yīng)包含來(lái)自窗格的網(wǎng)絡(luò)附件選擇批注的NetworkAttachmentDefinition對(duì)象名稱(chēng)，或者包含群集范圍的默認(rèn)網(wǎng)絡(luò)的名稱(chēng)。 “name”可以包含第4.1.1節(jié)中定義的命名空間引用。 [參考2018-02-01會(huì)議@ 22:30]
5.3.2 "interface"
此可選鍵的值（類(lèi)型字符串）應(yīng)包含與網(wǎng)絡(luò)附件對(duì)應(yīng)的pod的網(wǎng)絡(luò)命名空間中的網(wǎng)絡(luò)接口名稱(chēng)。
5.3.2.1 CNI Delegating Plugin Requirements
對(duì)于版本0.3.0或更高版本的CNI結(jié)果，“interface”鍵應(yīng)來(lái)自CNI Result的“interfaces”屬性的第一個(gè)元素，該屬性具有有效的“沙盒”屬性。
對(duì)于早于0.3.0的CNI結(jié)果版本，實(shí)現(xiàn)可以從為網(wǎng)絡(luò)附件操作設(shè)置的CNI_IFNAME環(huán)境變量填充該字段，或?qū)⒃撟侄瘟艨铡?/p>
5.3.3 "ips"
此可選鍵的值（類(lèi)型字符串?dāng)?shù)組）應(yīng)包含由于附件操作而分配給pod的IPv4和/或IPv6地址的數(shù)組。
5.3.3.1 CNI Delegating Plugin Requirements
對(duì)于版本0.3.0或更高版本的CNI結(jié)果，如果滿(mǎn)足以下任一條件，則“ips”密鑰應(yīng)來(lái)自CNI結(jié)果的“ips”屬性; 否則它不應(yīng)該包含在狀態(tài)圖中。
- “ips”鍵應(yīng)取自CNI Result對(duì)象的“ips”列表的元素，其中“interface”索引引用CNI Result對(duì)象的“interfaces”列表中帶有有效“sandbox”鍵的第一個(gè)元素。
- 如果CNI Result對(duì)象的“interfaces”列表中沒(méi)有元素，或者CNI Result對(duì)象的“interfaces”列表中沒(méi)有任何接口具有有效的“sandbox”屬性，則應(yīng)從第一個(gè)元素中獲取“ips”鍵。 CNI結(jié)果對(duì)象的“ips”列表，它沒(méi)有“interface”屬性或“interface”屬性小于零。
這些要求的目的是確保狀態(tài)圖中包含的IP地址與分配給pod中附件接口的IP地址相同，而不是CNI插件有時(shí)報(bào)告的非沙箱接口的地址。
對(duì)于早于0.3.0的版本的CNI結(jié)果，“ips”密鑰應(yīng)來(lái)自CNI結(jié)果的“ip4”和“ip6”屬性的組合。
5.3.4 "mac"
此可選鍵的值（類(lèi)型字符串）應(yīng)包含由“interface”鍵指定的網(wǎng)絡(luò)接口的硬件地址。 如果存在“mac”鍵，則還必須存在“interface”。
5.3.4.1 CNI Delegating Plugin Requirements
對(duì)于版本0.3.0或更高版本的CNI結(jié)果，“mac”鍵應(yīng)來(lái)自CNI Result的“interfaces”屬性的第一個(gè)元素，該屬性具有有效的“沙盒”屬性。
對(duì)于早于0.3.0的CNI結(jié)果版本，實(shí)現(xiàn)可以通過(guò)特定于實(shí)現(xiàn)的機(jī)制填充該字段，或?qū)⒃撟侄瘟艨铡?/p>
5.3.5 "default"
此必需鍵的值（類(lèi)型為boolean）應(yīng)指示此附件是群集范圍的默認(rèn)網(wǎng)絡(luò)的結(jié)果。 “網(wǎng)絡(luò)附件狀態(tài)注釋”列表中只有一個(gè)元素可以將“默認(rèn)”鍵設(shè)置為true。
5.3.6 "dns"
此可選鍵的值（類(lèi)型映射）應(yīng)包含由于網(wǎng)絡(luò)附件而收集的DNS信息。 地圖可能包含以下鍵。
5.3.6.1 "nameservers"
此可選鍵的值（類(lèi)型字符串?dāng)?shù)組）應(yīng)包含DNS服務(wù)器的IPv4和/或IPv6地址數(shù)組。
5.3.6.2 "domain"
此可選鍵的值（類(lèi)型字符串）應(yīng)包含網(wǎng)絡(luò)附件的本地域名。
5.3.6.3 "search"
此可選鍵的值（類(lèi)型字符串?dāng)?shù)組）應(yīng)包含網(wǎng)絡(luò)附件的DNS搜索名稱(chēng)數(shù)組。
5.4 Example
kind: Pod
metadata:
name: my-pod
namespace: my-namespace
annotations:
k8s.v1.cni.cncf.io/network-status: |
[
{
"name": "cluster-wide-default",
"interface": "eth5",
"ips": [ "1.2.3.1/24", "2001:abba::2230/64" ],
"mac": "02:11:22:33:44:54",
"default": true
},
{
"name": "some-network",
"interface": "eth1",
"ips": [ "1.2.3.4/24", "2001:abba::2234/64" ],
"mac": "02:11:22:33:44:55",
"dns": {
"nameservers": [ "4.2.2.1", "2001:4860:4860::8888" ],
"search": [ "eng.foobar.com", "foobar.com" ]
},
"default": false
},
{
"name": "other-ns/an-ip-over-infiniband-network",
"interface": "ib0",
"ips": [ "5.4.3.2/16" ],
"mac": "80:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22",
"default": false
}
]
6. Cluster-Wide Default Network
實(shí)現(xiàn)必須將每個(gè)pod連接到群集范圍的默認(rèn)網(wǎng)絡(luò)，從而保持現(xiàn)有的Kubernetes pod網(wǎng)絡(luò)行為。 [ref 2018-01-18 @ 31:30]實(shí)現(xiàn)可以自由定義如何配置和引用群集范圍的默認(rèn)網(wǎng)絡(luò)（例如，作為NetworkAttachmentDefinition對(duì)象，磁盤(pán)上的CNI JSON配置文件，或其他一些 如果所有pod都首先連接到該網(wǎng)絡(luò)，則意味著）。
6.1 Network Plugin Readiness
在群集范圍的默認(rèn)網(wǎng)絡(luò)準(zhǔn)備就緒之前，實(shí)現(xiàn)不應(yīng)將其CNI JSON配置文件寫(xiě)入Kubernetes CNI配置目錄。 這可以防止Kubernetes在節(jié)點(diǎn)上安排將立即失敗的pod，因?yàn)樵搶?shí)現(xiàn)已表示準(zhǔn)備就緒，但群集范圍的默認(rèn)網(wǎng)絡(luò)沒(méi)有。
該實(shí)現(xiàn)可以自由定義如何確定群集范圍的默認(rèn)網(wǎng)絡(luò)就緒性，前提是當(dāng)確定群集范圍的默認(rèn)網(wǎng)絡(luò)準(zhǔn)備就緒時(shí)，可以立即將pod連接到該網(wǎng)絡(luò)并具有合理的網(wǎng)絡(luò)連接期望。
6.1.1 CNI Delegating Plugin Recommendations
為了防止群集范圍的默認(rèn)網(wǎng)絡(luò)，實(shí)現(xiàn)和kubelet的CNI插件加載器之間的競(jìng)爭(zhēng)條件，建議通過(guò)--cni-conf-dir命令行選項(xiàng)為kubelet配置特定于實(shí)現(xiàn)的CNI配置目錄。
實(shí)現(xiàn)應(yīng)該等到群集范圍的默認(rèn)網(wǎng)絡(luò)插件的CNI JSON配置寫(xiě)入/etc/cni/net.d，然后將其自己的CNI JSON配置文件寫(xiě)入給予kubelet的特定于實(shí)現(xiàn)的CNI配置目錄。
6.1.2 Alternate Readiness Method
如果在指示實(shí)現(xiàn)準(zhǔn)備好kubelet之前無(wú)法等待群集范圍的默認(rèn)網(wǎng)絡(luò)準(zhǔn)備就緒，則實(shí)現(xiàn)可以立即將其自己的CNI配置文件安裝到kubelet CNI配置目錄，確保其配置優(yōu)先于群集 全范圍的默認(rèn)網(wǎng)絡(luò)（如果有的話）。 然后，實(shí)施必須阻止任何pod網(wǎng)絡(luò)連接/分離操作，直到群集范圍的默認(rèn)網(wǎng)絡(luò)準(zhǔn)備就緒。
6.2 Cluster-wide Default Network Attachment Ordering
在附加由“網(wǎng)絡(luò)附件選擇注釋”指定的任何網(wǎng)絡(luò)之前，實(shí)施必須附加群集范圍的默認(rèn)網(wǎng)絡(luò)。
7. Runtime and Implementation Considerations
7.1 CNI Delegating Plugin Requirements for CNI Configuration and Result Versioning
CNI委托插件必須符合CNI規(guī)范在CNI配置列表中調(diào)用插件的要求。 如果CNI委托插件使用CNI項(xiàng)目的引用“l(fā)ibcni”庫(kù)，則會(huì)自動(dòng)處理這些問(wèn)題。 如果沒(méi)有，CNI規(guī)范要求CNI委托插件將配置列表中的cniVersion和name字段注入每個(gè)插件調(diào)用的配置JSON。 這可確保configlist中的每個(gè)插件都能夠理解上一個(gè)插件的結(jié)果，并確保運(yùn)行時(shí)接收到正確版本的最終結(jié)果。
7.2 Attachment/Detachment Failure Handling
在pod網(wǎng)絡(luò)設(shè)置中，無(wú)法連接pod的網(wǎng)絡(luò)附件選擇注釋所引用的任何網(wǎng)絡(luò)，或者無(wú)法連接群集范圍的默認(rèn)網(wǎng)絡(luò)，應(yīng)立即使pod網(wǎng)絡(luò)設(shè)置操作失敗。 不應(yīng)嘗試尚未執(zhí)行的附件。
在pod網(wǎng)絡(luò)拆卸時(shí)，必須拆除在pod網(wǎng)絡(luò)設(shè)置期間嘗試的所有網(wǎng)絡(luò)附件，并且一個(gè)網(wǎng)絡(luò)附件的故障不能防止后續(xù)附件的拆除。 但是，如果任何分離失敗，則應(yīng)將最終錯(cuò)誤傳遞給運(yùn)行時(shí)以指示整體拆卸操作失敗。
7.3 Serialization of Network Attachment Operations
CNI規(guī)范0.4.0規(guī)定“容器運(yùn)行時(shí)不能為同一容器調(diào)用并行操作，但允許為不同容器調(diào)用并行操作。” 實(shí)現(xiàn)必須遵循此要求，并且不得并行化pod網(wǎng)絡(luò)附件操作。 在本規(guī)范的未來(lái)版本中可能會(huì)取消此要求。
7.4 Restrictions on Selection of Network Attachment Definitions by Pods
實(shí)現(xiàn)可以自由地對(duì)給定Pod可以選擇哪些網(wǎng)絡(luò)附件定義施加限制。 這可以通過(guò)RBAC，準(zhǔn)入控制或任何其他特定于實(shí)現(xiàn)的方法來(lái)完成。 如果實(shí)現(xiàn)確定Pod不允許為Pod選擇的給定網(wǎng)絡(luò)附件定義，則它必須使pod網(wǎng)絡(luò)操作失敗。
