SPEC: introduce "args" field and new error code

Based on previous discussions on the CNI maintainers calls, the spec is
unclear on 1) when CNI_ARGS should be used and 2) the fact the dynamic
config can be passed in through the network JSON.

This PR makes it clear that per-container config can be passed in
through the network JSON, adding a top level `args` field into
which orchestrators can add additional metadata without worrying that
plugins might reject the additional data. It also allows for plugins to
reject unknown fields passed in at the top level.

Using JSON is preferable to CNI_ARGS since it allows namespaced and
structured data. CNI_ARGS is a flat list of KV pairs which has reserved
characters with no escaping rules defined.
CNI_ARGS may still be used by orchestrators that want the simplicity of
passing the network config JSON as specified by the user, unchanged
through to the CNI plugin. But for any kind of structured data, it's
recommended that the `args` field in the JSON is used instead.

SPEC.md

@@ -23,6 +23,7 @@ The intention is for the container runtime to first create a new network namespa
 It then determines which networks this container should belong to and for each network, which plugin must be executed.
 The network configuration is in JSON format and can easily be stored in a file.
 The network configuration includes mandatory fields such as "name" and "type" as well as plugin (type) specific ones.
+The network configuration allows for fields to change values between invocations. For this purpose there is an optional field "args" which should contain the varying information.
 The container runtime sequentially sets up the networks by executing the corresponding plugin for each network.
 Upon completion of the container lifecycle, the runtime executes the plugins in reverse order (relative to the order in which they were added) to disconnect them from the networks.
 
@@ -46,7 +47,7 @@ The operations that the CNI plugin needs to support are:
     - **Container ID**. This is optional but recommended, and should be unique across an administrative domain while the container is live (it may be reused in the future). For example, an environment with an IPAM system may require that each container is allocated a unique ID and that each IP allocation can thus be correlated back to a particular container. As another example, in appc implementations this would be the _pod ID_.
     - **Network namespace path**. This represents the path to the network namespace to be added, i.e. /proc/[pid]/ns/net or a bind-mount/link to it.
     - **Network configuration**. This is a JSON document describing a network to which a container can be joined. The schema is described below.
-    - **Extra arguments**. This allows granular configuration of CNI plugins on a per-container basis.
+    - **Extra arguments**. This provides an alternative mechanism to allow simple configuration of CNI plugins on a per-container basis.
     - **Name of the interface inside the container**. This is the name that should be assigned to the interface created inside the container (network namespace); consequently it must comply with the standard Linux restrictions on interface names.
   - Result:
     - **IPs assigned to the interface**. This is either an IPv4 address, an IPv6 address, or both.
@@ -71,7 +72,7 @@ It will then look for this executable in a list of predefined directories. Once
 - `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"
 - `CNI_PATH`: Colon-separated list of paths to search for CNI plugin executables
 
-Network configuration in JSON format is streamed through stdin.
+Network configuration in JSON format is streamed to the plugin through stdin. This means it is not tied to a particular file on disk and can contain information which changes between invocations.
 
 
 ### Result
@@ -128,6 +129,7 @@ The network configuration is described in JSON form. The configuration can be st
 - `cniVersion` (string): [Semantic Version 2.0](http://semver.org) of CNI specification to which this configuration conforms.
 - `name` (string): Network name. This should be unique across all containers on the host (or other administrative domain).
 - `type` (string): Refers to the filename of the CNI plugin executable.
+- `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`.
 - `ipMasq` (boolean): Optional (if supported by the plugin). Set up an IP masquerade on the host for this network. This is necessary if the host will act as a gateway to subnets that are not able to route to the IP assigned to the container.
 - `ipam`: Dictionary with IPAM specific values:
   - `type` (string): Refers to the filename of the IPAM plugin executable.
@@ -140,6 +142,7 @@ The network configuration is described in JSON form. The configuration can be st
   - `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
 
+Plugins may define additional fields that they accept and may generate an error if called with unknown fields. The exception to this is the `args` field may be used to pass arbitrary data which may be ignored by plugins.
 ### Example configurations
 
 ```json
@@ -173,6 +176,12 @@ The network configuration is described in JSON form. The configuration can be st
     "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"
+    }
+  }
 }
 ```
 
@@ -201,7 +210,7 @@ To lessen the burden and make IP management strategy be orthogonal to the type o
 
 #### IP Address Management (IPAM) Interface
 
-Like CNI plugins, the IPAM plugins are invoked by running an executable. The executable is searched for in a predefined list of paths, indicated to the CNI plugin via `CNI_PATH`. The IPAM Plugin receives all the same environment variables that were passed in to the CNI plugin. Just like the CNI plugin, IPAM receives the network configuration file via stdin.
+Like CNI plugins, the IPAM plugins are invoked by running an executable. The executable is searched for in a predefined list of paths, indicated to the CNI plugin via `CNI_PATH`. The IPAM Plugin receives all the same environment variables that were passed in to the CNI plugin. Just like the CNI plugin, IPAM receives the network configuration via stdin.
 
 Success is indicated by a zero return code and the following JSON being printed to stdout (in the case of the ADD command):
 
@@ -255,3 +264,4 @@ IPAM plugin examples:
 
 ## Well-known Error Codes
 - `1` - Incompatible CNI version
+- `2` - Unsupported field in network configuration. The error message must contain the key and value of the unsupported field.