From d716d73444232f62c6b91a0fafbbe9c868ee01a8 Mon Sep 17 00:00:00 2001 From: Tom Denham Date: Tue, 17 Jan 2017 15:53:24 -0800 Subject: [PATCH] Documentation: Add conventions doc --- CONVENTIONS.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 CONVENTIONS.md diff --git a/CONVENTIONS.md b/CONVENTIONS.md new file mode 100644 index 00000000..b21a81a1 --- /dev/null +++ b/CONVENTIONS.md @@ -0,0 +1,51 @@ +# Extension conventions + +The Container Network Interface (CNI) currently provides two methods for passing additional information to plugins without needing to update the spec. These are the `CNI_ARGS` environment variable and the `args` field in the JSON config. + +Establishing these conventions allows plugins to work across multiple runtimes. This helps both plugins and the runtimes. + +## Plugins +* Plugin authors should aim to support these conventions where it makes sense for their plugin. This means they are more likely to "just work" with a wider range of runtimes. + +## Runtimes +* Runtime authors should follow these conventions if they want to pass additional information to plugins. This will allow the extra information to be consumed by the widest range of plugins. + +# Current conventions +Additional conventions can be created by creating PRs which modify this document. + +## CNI_ARGS +CNI_ARGS formed part of the original CNI spec and have been present since the initial release. +> `CNI_ARGS`: Extra arguments passed in by the user at invocation time. Alphanumeric key-value pairs separated by semicolons; for example, "FOO=BAR;ABC=123" + +| Field | Purpose| Spec and Example | Runtime implementations | Plugin Implementations | +| ------ | ------ | ------ | ------ | ------ | ------ | +| IP | Request a specific IP from IPAM plugins | IP=192.168.10.4 | *rkt* supports passing additional arguments to plugins and the [documentation](https://coreos.com/rkt/docs/latest/networking/overriding-defaults.html) suggests IP can be used. | host-local (since version v0.2.0) supports the field for IPv4 only - [documentation](https://github.com/containernetworking/cni/blob/master/Documentation/host-local.md#supported-arguments).| + +## "args" in network config +`args` in [network config](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration) were introduced as an optional field into the `0.1.0` CNI spec. The first CNI code release that it appeared in was `v0.4.0`. +> args (dictionary): Optional additional arguments provided by the container runtime. For example a dictionary of labels could be passed to CNI plugins by adding them to a labels field under args. + +`args` provide a way of providing more structured data than the flat strings that CNI_ARGS can support. + +The conventions documented here are all namepaced under `cni` so they don't conflict with any existing `args`. + +```json +{ + "cniVersion":"0.2.0", + "name":"net", + "args":{ + "cni":{ + "example":"value" + } + }, + + "ipam":{ + + } +} +``` + +| Area | Purpose| Spec and Example | Runtime implementations | Plugin Implementations | +| ------ | ------ | ------ | ------ | ------ | ------ | +| labels | Pass`key=value` labels to plugins | 
"labels" : [
  { "key" : "app", "value" : "myapp" },
  { "key" : "env", "value" : "prod" }
]
| none | none | +| port mappings | Pass mapping from ports on the host to ports in the container network namespace. | 
"port_mappings" : [
  { "host_port": 8080, "container_port": 80, "protocol": "tcp" },
  { "host_port": 8000, "container_port": 8001, "protocol": "udp" }
]
| none | none |