SPEC: containernetworking#928 support non-inlined plugin loading

Signed-off-by: Benjamin Leggett <benjamin.leggett@solo.io>
bleggett · Apr 22, 2024 · 333aafe · 333aafe
1 parent 79876e3
commit 333aafe
Showing 1 changed file with 100 additions and 16 deletions.
diff --git a/SPEC.md b/SPEC.md
@@ -109,13 +109,15 @@ A network configuration consists of a JSON object with the following keys:
 
 - `cniVersion` (string): [Semantic Version 2.0](https://semver.org) of CNI specification to which this configuration list and all the individual configurations conform. Currently "1.1.0"
 - `cniVersions` (string list): List of all CNI versions which this configuration supports. See [version selection](#version-selection) below.
-- `name` (string): Network name. This should be unique across all network configurations on a host (or other administrative domain).  Must start with an alphanumeric character, optionally followed by any combination of one or more alphanumeric characters, underscore, dot (.) or hyphen (-).
+- `name` (string): Network name. This should be unique across all network configurations on a host (or other administrative domain).  Must start with an alphanumeric character, optionally followed by any combination of one or more alphanumeric characters, underscore, dot (.) or hyphen (-). Must not contain characters disallowed in file paths.
 - `disableCheck` (boolean): Either `true` or `false`.  If `disableCheck` is `true`, runtimes must not call `CHECK` for this network configuration list.  This allows an administrator to prevent `CHECK`ing where a combination of plugins is known to return spurious errors.
-- `plugins` (list): A list of CNI plugins and their configuration, which is a list of plugin configuration objects.
+- `loadOnlyInlinedPlugins` (boolean): Either `true` or `false`. If `false` (default), indicates [plugin configuration objects](#plugin-configuration-objects) can be aggregated from multiple sources. Any valid plugin configuration objects aggregated from other sources must be appended to the final list of `plugins` for that network name. If set to `true`, indicates that valid plugin configuration objects aggregated from sources other than the main network configuration will be ignored. If `plugins` is not present in the network configuration, `loadOnlyInlinedPlugins` cannot be set to `true`.
+- `plugins` (list): A list of inlined [plugin configuration objects](#plugin-configuration-objects). If this key is populated with inlined plugin objects, and `loadOnlyInlinedPlugins` is true, the final set of plugins for a network must consist of all the plugin objects in this list, merged with all the plugins loaded from the sibling folder with the same name as the network.
 
 #### Plugin configuration objects:
-Plugin configuration objects may contain additional fields than the ones defined here.
-The runtime MUST pass through these fields, unchanged, to the plugin, as defined in section 3.
+Runtimes may aggregate plugin configuration objects from multiple sources, and must unambiguously associate each loaded plugin configuration object with a single, valid network configuration. All aggregated plugin configuration objects must be validated, and each plugin with a valid configuration object must be invoked.
+
+Plugin configuration objects may contain additional fields beyond the ones defined here. The runtime MUST pass through these fields, unchanged, to the invoked plugin, as defined in section 3.
 
 **Required keys:**
 - `type` (string): Matches the name of the CNI plugin binary on disk. Must not contain characters disallowed in file paths for the system (e.g. / or \\).
@@ -146,18 +148,68 @@ Plugins that consume any of these configuration keys should respect their intend
 Plugins may define additional fields that they accept and may generate an error if called with unknown fields. Runtimes must preserve unknown fields in plugin configuration objects when transforming for execution.
 
 #### Example configuration
+Network configuration with no inlined plugin confs, and two loaded plugin confs:
+`/etc/cni/net.d/10-dbnet.conf`:
 ```jsonc
 {
   "cniVersion": "1.1.0",
   "cniVersions": ["0.3.1", "0.4.0", "1.0.0", "1.1.0"],
   "name": "dbnet",
-  "plugins": [
+  "loadOnlyInlinedPlugins": false,
+}
+```
+
+`/etc/cni/net.d/dbnet/5-bridge.conf`:
+```jsonc
+{
+  "type": "bridge",
+  // plugin specific parameters
+  "bridge": "cni0",
+  "keyA": ["some more", "plugin specific", "configuration"],
+
+  "ipam": {
+    "type": "host-local",
+    // ipam specific
+    "subnet": "10.1.0.0/16",
+    "gateway": "10.1.0.1",
+    "routes": [
+        {"dst": "0.0.0.0/0"}
+    ]
+  },
+  "dns": {
+    "nameservers": [ "10.1.0.1" ]
+  }
+}
+```
+
+`/etc/cni/net.d/dbnet/10-tuning.conf`:
+```jsonc
+{
+  "type": "tuning",
+  "capabilities": {
+    "mac": true
+  },
+  "sysctl": {
+    "net.core.somaxconn": "500"
+  }
+}
+```
+
+Network configuration with one inlined plugin conf, and one loaded plugin conf:
+`/etc/cni/net.d/10-dbnet.conf`:
+```jsonc
+{
+  "cniVersion": "1.1.0",
+  "cniVersions": ["0.3.1", "0.4.0", "1.0.0", "1.1.0"],
+  "name": "dbnet",
+  "loadOnlyInlinedPlugins": false,
+  plugins: [
     {
       "type": "bridge",
       // plugin specific parameters
       "bridge": "cni0",
       "keyA": ["some more", "plugin specific", "configuration"],
-      
+
       "ipam": {
         "type": "host-local",
         // ipam specific
@@ -170,19 +222,51 @@ Plugins may define additional fields that they accept and may generate an error
       "dns": {
         "nameservers": [ "10.1.0.1" ]
       }
-    },
+    }
+  ]
+}
+```
+
+`/etc/cni/net.d/dbnet/10-tuning.conf`:
+```jsonc
+{
+  "type": "tuning",
+  "capabilities": {
+    "mac": true
+  },
+  "sysctl": {
+    "net.core.somaxconn": "500"
+  }
+}
+```
+
+Network configuration with one inlined plugin conf, and no loaded plugin conf:
+`/etc/cni/net.d/10-dbnet.conf`:
+```jsonc
+{
+  "cniVersion": "1.1.0",
+  "cniVersions": ["0.3.1", "0.4.0", "1.0.0", "1.1.0"],
+  "name": "dbnet",
+  "loadOnlyInlinedPlugins": true,
+  "plugins": [
     {
-      "type": "tuning",
-      "capabilities": {
-        "mac": true
+      "type": "bridge",
+      // plugin specific parameters
+      "bridge": "cni0",
+      "keyA": ["some more", "plugin specific", "configuration"],
+
+      "ipam": {
+        "type": "host-local",
+        // ipam specific
+        "subnet": "10.1.0.0/16",
+        "gateway": "10.1.0.1",
+        "routes": [
+            {"dst": "0.0.0.0/0"}
+        ]
       },
-      "sysctl": {
-        "net.core.somaxconn": "500"
+      "dns": {
+        "nameservers": [ "10.1.0.1" ]
       }
-    },
-    {
-        "type": "portmap",
-        "capabilities": {"portMappings": true}
     }
   ]
 }