From 3fbf94a90a14c237eafb49147e3729f095e77bcd Mon Sep 17 00:00:00 2001 From: Tom Denham Date: Wed, 8 Feb 2017 12:43:04 -0800 Subject: [PATCH 1/3] CONVENTIONS.md: Update details on port-mappings After discussion with the CNI maintainers and representatives from Mesos and Kubernetes we've settled on this approach for passing the dynamic port mapping information from runtimes to plugins. Including it in the plugin config allows "operators" to signal that they expect port mapping information to be passed to a specific plugin (or plugins). This follows the model that config passed in the plugin config should be acted upon by a plugin. Runtimes can optionally return an error to users if they find no plugin in the chain that supports port mappings. I'm sure we'd all like to see this merged soon so I'll try to turn any feedback quickly (and I'm happy to get any and all feedback - spellings, unclear working, wrong JSON terminology etc..) --- CONVENTIONS.md | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index ec455f29..589d9d62 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -21,13 +21,37 @@ Additional conventions can be created by creating PRs which modify this document [Plugin specific fields](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration) formed part of the original CNI spec and have been present since the initial release. > 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. -A plugin can define any additional fields it needs to work properly. It is expected that it will return an error if if can't act on fields that were expected or where the field values were malformed. +A plugin can define any additional fields it needs to work properly. It is expected that it will return an error if it can't act on fields that were expected or where the field values were malformed. -This method of passing information to a plugin is recommended when the information should be acted on and has specific meaning to that plugin. +This method of passing information to a plugin is recommended when the information has specific meaning to the plugin that it's passed to and when the plugin should act on it or return an error if it can't. + +Dynamic information (i.e. data that a runtime fills out) should be placed in a `runtime_config` section. | Area | Purpose| Spec and Example | Runtime implementations | Plugin Implementations | | ------ | ------ | ------ | ------ | ------ | ------ | -| 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 | +| port mappings | Pass mapping from ports on the host to ports in the container network namespace. | Runtimes should receive the follow plugin config 
"runtime_config": {port_mappings": []}
Runtimes should fill in the actual port mappings when the config is passed to plugins e.g. 
"runtime_config": {
  "port_mappings" : [
    { "host_port": 8080, "container_port": 80, "protocol": "tcp" },
    { "host_port": 8000, "container_port": 8001, "protocol": "udp" }
  ]
}
| none | none | + +For example, the configuration for a port mapping plugin might look like this to an operator (it should be included as part of a [network configuration list](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration-lists). +```json +{ + "name" : "ExamplePlugin", + "type" : "port-mapper", + "runtime_config": {"port_mappings": []} +} +``` + +But the runtime would fill in the mappings so the plugin itself would receive something like this. +```json +{ + "name" : "ExamplePlugin", + "type" : "port-mapper", + "runtime_config": { + "port_mappings": [ + {"host_port": 8080, "container_port": 80, "protocol": "tcp"} + ] + } +} +``` ## "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`. From 95ca9d393a8df7bfcb2153636c9007e60acd5c77 Mon Sep 17 00:00:00 2001 From: Tom Denham Date: Thu, 9 Feb 2017 14:03:47 -0800 Subject: [PATCH 2/3] Update with feedback --- CONVENTIONS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 589d9d62..82857533 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -29,14 +29,14 @@ Dynamic information (i.e. data that a runtime fills out) should be placed in a ` | Area | Purpose| Spec and Example | Runtime implementations | Plugin Implementations | | ------ | ------ | ------ | ------ | ------ | ------ | -| port mappings | Pass mapping from ports on the host to ports in the container network namespace. | Runtimes should receive the follow plugin config 
"runtime_config": {port_mappings": []}
Runtimes should fill in the actual port mappings when the config is passed to plugins e.g. 
"runtime_config": {
  "port_mappings" : [
    { "host_port": 8080, "container_port": 80, "protocol": "tcp" },
    { "host_port": 8000, "container_port": 8001, "protocol": "udp" }
  ]
}
| none | none | +| port mappings | Pass mapping from ports on the host to ports in the container network namespace. | Operators can ask runtimes to pass port mapping information to plugins, by setting the following in the CNI config 
"capabilities": {port_mappings": true}
Runtimes should fill in the actual port mappings when the config is passed to plugins. It should be placed in a new section of the config "runtime_config" e.g. 
"runtime_config": {
  "port_mappings" : [
    { "host_port": 8080, "container_port": 80, "protocol": "tcp" },
    { "host_port": 8000, "container_port": 8001, "protocol": "udp" }
  ]
}
| none | none | For example, the configuration for a port mapping plugin might look like this to an operator (it should be included as part of a [network configuration list](https://github.com/containernetworking/cni/blob/master/SPEC.md#network-configuration-lists). ```json { "name" : "ExamplePlugin", "type" : "port-mapper", - "runtime_config": {"port_mappings": []} + "capabilities": {"port_mappings": true} } ``` From e3da6e1cfb7df6f8f0a8dde89b6accf2bbc7c64c Mon Sep 17 00:00:00 2001 From: Tom Denham Date: Mon, 13 Feb 2017 10:14:45 -0800 Subject: [PATCH 3/3] More markups --- CONVENTIONS.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 82857533..894b73d2 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -10,9 +10,11 @@ Establishing these conventions allows plugins to work across multiple 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. +* Plugins should accept arguments according to these conventions if they implement the same basic functionality as other plugins. If plugins have shared functionality that isn't coverered by these conventions then a PR should be opened against this document. ## 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. +* These conventions serve as an abstraction for the runtime. For example, port forwarding is highly implementation specific, but users should be able to select the plugin of their choice without changing the runtime. # Current conventions Additional conventions can be created by creating PRs which modify this document. @@ -23,7 +25,9 @@ Additional conventions can be created by creating PRs which modify this document A plugin can define any additional fields it needs to work properly. It is expected that it will return an error if it can't act on fields that were expected or where the field values were malformed. -This method of passing information to a plugin is recommended when the information has specific meaning to the plugin that it's passed to and when the plugin should act on it or return an error if it can't. +This method of passing information to a plugin is recommended when the following conditions hold +* The configuration has specific meaning to the plugin (i.e. it's not just general meta data) +* the plugin is expected to act on the configuration or return an error if it can't Dynamic information (i.e. data that a runtime fills out) should be placed in a `runtime_config` section.