Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

spec: add extras for adding additional info in result. #749

Closed
wants to merge 2 commits into from
+40 −8
Closed

spec: add extras for adding additional info in result. #749

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
68c93d0
spec: add `capabilityArgs` for adding additional info in result.
Colstuwjx Feb 11, 2020
8d23ee2
update the wording and also applied to cni plugins according reviewer…
Colstuwjx Mar 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 40 additions & 8 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.

```
{
Expand Down Expand Up @@ -193,6 +194,10 @@ Plugins must indicate success with a return code of zero and the following JSON
"domain": <name-of-local-domain> (optional)
"search": <list-of-additional-search-domains> (optional)
"options": <list-of-options> (optional)
},
"extras": { (optional)
"<name-of-the-arg>": <value-of-the-arg> (optional)
...
}
}
```
Expand All @@ -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.

Expand Down Expand Up @@ -444,7 +452,8 @@ Note that the runtime adds the `cniVersion` and `name` fields from configuration
],
"dns": {
"nameservers": [ "10.1.0.1" ]
}
},
"extras": {},
}
}
```
Expand Down Expand Up @@ -498,7 +507,8 @@ Given the same network configuration JSON list, the container runtime would perf
],
"dns": {
"nameservers": [ "10.1.0.1" ]
}
},
"extras": {},
}
}
```
Expand Down Expand Up @@ -538,7 +548,8 @@ Given the same network configuration JSON list, the container runtime would perf
],
"dns": {
"nameservers": [ "10.1.0.1" ]
}
},
"extras": {},
}
}
```
Expand Down Expand Up @@ -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": {},
}
}
```
Expand Down Expand Up @@ -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": {}
}
}
```
Expand Down Expand Up @@ -667,12 +680,16 @@ Success must be indicated by a zero return code and the following JSON being pri
"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)
},
"extras": { (optional)
"<name-of-the-arg>": <value-of-the-arg> (optional)
...
}
}
```
Expand All @@ -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:
Expand Down Expand Up @@ -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)
"<name-of-the-arg>": <value-of-the-arg> (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.
Expand Down