diff --git a/SPEC.md b/SPEC.md index 436f18b4..8cc127cd 100644 --- a/SPEC.md +++ b/SPEC.md @@ -89,6 +89,7 @@ The operations that CNI plugins must support are: - **Interfaces list**. Depending on the plugin, this can include the sandbox (eg, container or hypervisor) interface name and/or the host interface name, the hardware addresses of each interface, and details about the sandbox (if any) the interface is in. - **IP configuration assigned to each interface**. The IPv4 and/or IPv6 addresses, gateways, and routes assigned to sandbox and/or host interfaces. - **DNS information**. Dictionary that includes DNS information for nameservers, domain, search domains and options. + - **Extra result**. An optional dictionary that includes additional information, it could be consumed by the downstream plugins for making some plugin-specifically tasks. - `DEL`: Delete container from network - Parameters: @@ -160,7 +161,7 @@ Network configuration in JSON format must be streamed to the plugin through stdi Note that IPAM plugins should return an abbreviated `Result` structure as described in [IP Allocation](#ip-allocation). -Plugins must indicate success with a return code of zero and the following JSON printed to stdout in the case of the ADD command. The `ips` and `dns` items should be the same output as was returned by the IPAM plugin (see [IP Allocation](#ip-allocation) for details) except that the plugin should fill in the `interface` indexes appropriately, which are missing from IPAM plugin output since IPAM plugins should be unaware of interfaces. +Plugins must indicate success with a return code of zero and the following JSON printed to stdout in the case of the ADD command. The `ips`, `dns` items should be the same output as was returned by the IPAM plugin (see [IP Allocation](#ip-allocation) for details) except that the plugin should fill in the `interface` indexes appropriately, which are missing from IPAM plugin output since IPAM plugins should be unaware of interfaces. The `extras` item is optional, if it is set, the plugin is free to update it or keep it with the same. ``` { @@ -193,6 +194,10 @@ Plugins must indicate success with a return code of zero and the following JSON "domain": (optional) "search": (optional) "options": (optional) + }, + "extras": { (optional) + "": (optional) + ... } } ``` @@ -216,6 +221,9 @@ See the [Routes well-known structure](#routes) section for more information. The `dns` field contains a dictionary consisting of common DNS information. See the [DNS well-known structure](#dns) section for more information. +The `extras` field contains a dictionary which carries additional plugin execution information. +See the [Extras well-known structure](#extras) section for more information. + The specification does not declare how this information must be processed by CNI consumers. Examples include generating an `/etc/resolv.conf` file to be injected into the container filesystem or running a DNS forwarder on the host. @@ -444,7 +452,8 @@ Note that the runtime adds the `cniVersion` and `name` fields from configuration ], "dns": { "nameservers": [ "10.1.0.1" ] - } + }, + "extras": {}, } } ``` @@ -498,7 +507,8 @@ Given the same network configuration JSON list, the container runtime would perf ], "dns": { "nameservers": [ "10.1.0.1" ] - } + }, + "extras": {}, } } ``` @@ -538,7 +548,8 @@ Given the same network configuration JSON list, the container runtime would perf ], "dns": { "nameservers": [ "10.1.0.1" ] - } + }, + "extras": {}, } } ``` @@ -581,7 +592,8 @@ Note that plugins are executed in reverse order from the `ADD` and `CHECK` actio ], "dns": { "nameservers": [ "10.1.0.1" ] - } + }, + "extras": {}, } } ``` @@ -633,7 +645,8 @@ Note that plugins are executed in reverse order from the `ADD` and `CHECK` actio ], "dns": { "nameservers": [ "10.1.0.1" ] - } + }, + "extras": {} } } ``` @@ -667,12 +680,16 @@ Success must be indicated by a zero return code and the following JSON being pri "gw": "" (optional) }, ... - ] + ], "dns": { (optional) "nameservers": (optional) "domain": (optional) "search": (optional) "options": (optional) + }, + "extras": { (optional) + "": (optional) + ... } } ``` @@ -690,6 +707,9 @@ See the [Routes well-known structure](#routes) section for more information. The `dns` field contains a dictionary consisting of common DNS information. See the [DNS well-known structure](#dns) section for more information. +The `extras` field contains a dictionary which carries additional plugin execution information. +See the [Extras well-known structure](#extras) section for more information. + Errors and logs are communicated in the same way as the CNI plugin. See [CNI Plugin Result](#result) section for details. IPAM plugin examples: @@ -763,7 +783,19 @@ The `dns` field contains a dictionary consisting of common DNS information. - `search` (list of strings): list of priority ordered search domains for short hostname lookups. Will be preferred over `domain` by most resolvers. - `options` (list of strings): list of options that can be passed to the resolver. See [CNI Plugin Result](#result) section for more information. - + +#### Extras + +``` + "extras": { (optional) + "": (optional) + ... + } +``` + +The `extras` field contains a dictionary which carries additional plugin execution information. +For the each item of `extras`, both the key and value are string type. If `extras` is set, it could be passed through the chain, and the downstream plugins could consume this additional information. + ## Well-known Error Codes Error codes 1-99 must not be used other than as specified here.