Initial stab at supporting subdirectory-based plugin conf loading

Signed-off-by: Benjamin Leggett <[email protected]>
containernetworking · Jan 15, 2024 · 86d1bcf · 86d1bcf
1 parent b62753a
commit 86d1bcf
Show file tree

Hide file tree

Showing 9 changed files with 299 additions and 111 deletions.
diff --git a/SPEC.md b/SPEC.md
@@ -109,13 +109,14 @@ 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. A path segment (such as a filesystem directory) with the same name as the network name, containing one or more plugin configuration JSON objects for that network, should exist at the same level as the network configuration object itself.
 - `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.
+<!-- - `plugins` (list): A list of CNI plugins and their configuration, which is a list of plugin configuration objects. -->
 
 #### 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.
+All plugin configuration objects present in a directory with the same name as a valid network configuration must be parsed, and each plugin with a parsable 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,48 +147,61 @@ 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
+
+`/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": [
-    {
-      "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" ]
-      }
-    },
-    {
-      "type": "tuning",
-      "capabilities": {
-        "mac": true
-      },
-      "sysctl": {
-        "net.core.somaxconn": "500"
-      }
-    },
-    {
-        "type": "portmap",
-        "capabilities": {"portMappings": true}
-    }
-  ]
 }
 ```
 
+`/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"
+  }
+},
+```
+
+`/etc/cni/net.d/dbnet/15-portmap.conf`:
+```jsonc
+{
+    "type": "portmap",
+    "capabilities": {"portMappings": true}
+}
+
+```
+
 ### Version considerations
 
 CNI runtimes, plugins, and network configurations may support multiple CNI specification versions independently. Plugins indicate their set of supported versions through the VERSION command, while network configurations indicate their set of supported versions through the `cniVersion` and `cniVersions` fields.

diff --git a/libcni/api.go b/libcni/api.go
@@ -66,16 +66,20 @@ type RuntimeConf struct {
 	CacheDir string
 }
 
-type NetworkConfig struct {
-	Network *types.NetConf
+// Deprecated: Use PluginConfig instead of NetworkConfig, the NetworkConfig
+// backwards-compat alias will be removed in a future release.
+type NetworkConfig = PluginConfig
+
+type PluginConfig struct {
+	Network *types.PluginConf
 	Bytes   []byte
 }
 
 type NetworkConfigList struct {
 	Name         string
 	CNIVersion   string
 	DisableCheck bool
-	Plugins      []*NetworkConfig
+	Plugins      []*PluginConfig
 	Bytes        []byte
 }
 
@@ -104,14 +108,14 @@ type CNI interface {
 	GetNetworkListCachedResult(net *NetworkConfigList, rt *RuntimeConf) (types.Result, error)
 	GetNetworkListCachedConfig(net *NetworkConfigList, rt *RuntimeConf) ([]byte, *RuntimeConf, error)
 
-	AddNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) (types.Result, error)
-	CheckNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) error
-	DelNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) error
-	GetNetworkCachedResult(net *NetworkConfig, rt *RuntimeConf) (types.Result, error)
-	GetNetworkCachedConfig(net *NetworkConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error)
+	AddNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) (types.Result, error)
+	CheckNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error
+	DelNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error
+	GetNetworkCachedResult(net *PluginConfig, rt *RuntimeConf) (types.Result, error)
+	GetNetworkCachedConfig(net *PluginConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error)
 
 	ValidateNetworkList(ctx context.Context, net *NetworkConfigList) ([]string, error)
-	ValidateNetwork(ctx context.Context, net *NetworkConfig) ([]string, error)
+	ValidateNetwork(ctx context.Context, net *PluginConfig) ([]string, error)
 
 	GCNetworkList(ctx context.Context, net *NetworkConfigList, args *GCArgs) error
 	GetStatusNetworkList(ctx context.Context, net *NetworkConfigList) error
@@ -147,7 +151,7 @@ func NewCNIConfigWithCacheDir(path []string, cacheDir string, exec invoke.Exec)
 	}
 }
 
-func buildOneConfig(name, cniVersion string, orig *NetworkConfig, prevResult types.Result, rt *RuntimeConf) (*NetworkConfig, error) {
+func buildOneConfig(name, cniVersion string, orig *PluginConfig, prevResult types.Result, rt *RuntimeConf) (*PluginConfig, error) {
 	var err error
 
 	inject := map[string]interface{}{
@@ -183,7 +187,7 @@ func buildOneConfig(name, cniVersion string, orig *NetworkConfig, prevResult typ
 // capabilities include "portMappings", and the CapabilityArgs map includes a
 // "portMappings" key, that key and its value are added to the "runtimeConfig"
 // dictionary to be passed to the plugin's stdin.
-func injectRuntimeConfig(orig *NetworkConfig, rt *RuntimeConf) (*NetworkConfig, error) {
+func injectRuntimeConfig(orig *PluginConfig, rt *RuntimeConf) (*PluginConfig, error) {
 	var err error
 
 	rc := make(map[string]interface{})
@@ -404,7 +408,7 @@ func (c *CNIConfig) GetNetworkListCachedResult(list *NetworkConfigList, rt *Runt
 
 // GetNetworkCachedResult returns the cached Result of the previous
 // AddNetwork() operation for a network, or an error.
-func (c *CNIConfig) GetNetworkCachedResult(net *NetworkConfig, rt *RuntimeConf) (types.Result, error) {
+func (c *CNIConfig) GetNetworkCachedResult(net *PluginConfig, rt *RuntimeConf) (types.Result, error) {
 	return c.getCachedResult(net.Network.Name, net.Network.CNIVersion, rt)
 }
 
@@ -416,7 +420,7 @@ func (c *CNIConfig) GetNetworkListCachedConfig(list *NetworkConfigList, rt *Runt
 
 // GetNetworkCachedConfig copies the input RuntimeConf to output
 // RuntimeConf with fields updated with info from the cached Config.
-func (c *CNIConfig) GetNetworkCachedConfig(net *NetworkConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error) {
+func (c *CNIConfig) GetNetworkCachedConfig(net *PluginConfig, rt *RuntimeConf) ([]byte, *RuntimeConf, error) {
 	return c.getCachedConfig(net.Network.Name, rt)
 }
 
@@ -479,7 +483,7 @@ func (c *CNIConfig) GetCachedAttachments(containerID string) ([]*NetworkAttachme
 	return attachments, nil
 }
 
-func (c *CNIConfig) addNetwork(ctx context.Context, name, cniVersion string, net *NetworkConfig, prevResult types.Result, rt *RuntimeConf) (types.Result, error) {
+func (c *CNIConfig) addNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) (types.Result, error) {
 	c.ensureExec()
 	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
 	if err != nil {
@@ -521,7 +525,7 @@ func (c *CNIConfig) AddNetworkList(ctx context.Context, list *NetworkConfigList,
 	return result, nil
 }
 
-func (c *CNIConfig) checkNetwork(ctx context.Context, name, cniVersion string, net *NetworkConfig, prevResult types.Result, rt *RuntimeConf) error {
+func (c *CNIConfig) checkNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) error {
 	c.ensureExec()
 	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
 	if err != nil {
@@ -563,7 +567,7 @@ func (c *CNIConfig) CheckNetworkList(ctx context.Context, list *NetworkConfigLis
 	return nil
 }
 
-func (c *CNIConfig) delNetwork(ctx context.Context, name, cniVersion string, net *NetworkConfig, prevResult types.Result, rt *RuntimeConf) error {
+func (c *CNIConfig) delNetwork(ctx context.Context, name, cniVersion string, net *PluginConfig, prevResult types.Result, rt *RuntimeConf) error {
 	c.ensureExec()
 	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
 	if err != nil {
@@ -603,7 +607,7 @@ func (c *CNIConfig) DelNetworkList(ctx context.Context, list *NetworkConfigList,
 	return nil
 }
 
-func pluginDescription(net *types.NetConf) string {
+func pluginDescription(net *types.PluginConf) string {
 	if net == nil {
 		return "<missing>"
 	}
@@ -617,7 +621,7 @@ func pluginDescription(net *types.NetConf) string {
 }
 
 // AddNetwork executes the plugin with the ADD command
-func (c *CNIConfig) AddNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) (types.Result, error) {
+func (c *CNIConfig) AddNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) (types.Result, error) {
 	result, err := c.addNetwork(ctx, net.Network.Name, net.Network.CNIVersion, net, nil, rt)
 	if err != nil {
 		return nil, err
@@ -631,7 +635,7 @@ func (c *CNIConfig) AddNetwork(ctx context.Context, net *NetworkConfig, rt *Runt
 }
 
 // CheckNetwork executes the plugin with the CHECK command
-func (c *CNIConfig) CheckNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) error {
+func (c *CNIConfig) CheckNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error {
 	// CHECK was added in CNI spec version 0.4.0 and higher
 	if gtet, err := version.GreaterThanOrEqualTo(net.Network.CNIVersion, "0.4.0"); err != nil {
 		return err
@@ -647,7 +651,7 @@ func (c *CNIConfig) CheckNetwork(ctx context.Context, net *NetworkConfig, rt *Ru
 }
 
 // DelNetwork executes the plugin with the DEL command
-func (c *CNIConfig) DelNetwork(ctx context.Context, net *NetworkConfig, rt *RuntimeConf) error {
+func (c *CNIConfig) DelNetwork(ctx context.Context, net *PluginConfig, rt *RuntimeConf) error {
 	var cachedResult types.Result
 
 	// Cached result on DEL was added in CNI spec version 0.4.0 and higher
@@ -707,7 +711,7 @@ func (c *CNIConfig) ValidateNetworkList(ctx context.Context, list *NetworkConfig
 // ValidateNetwork checks that a configuration is reasonably valid.
 // It uses the same logic as ValidateNetworkList)
 // Returns a list of capabilities
-func (c *CNIConfig) ValidateNetwork(ctx context.Context, net *NetworkConfig) ([]string, error) {
+func (c *CNIConfig) ValidateNetwork(ctx context.Context, net *PluginConfig) ([]string, error) {
 	caps := []string{}
 	for c, ok := range net.Network.Capabilities {
 		if ok {
@@ -819,7 +823,7 @@ func (c *CNIConfig) GCNetworkList(ctx context.Context, list *NetworkConfigList,
 	return joinErrors(errs...)
 }
 
-func (c *CNIConfig) gcNetwork(ctx context.Context, net *NetworkConfig) error {
+func (c *CNIConfig) gcNetwork(ctx context.Context, net *PluginConfig) error {
 	c.ensureExec()
 	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
 	if err != nil {
@@ -854,7 +858,7 @@ func (c *CNIConfig) GetStatusNetworkList(ctx context.Context, list *NetworkConfi
 	return nil
 }
 
-func (c *CNIConfig) getStatusNetwork(ctx context.Context, net *NetworkConfig) error {
+func (c *CNIConfig) getStatusNetwork(ctx context.Context, net *PluginConfig) error {
 	c.ensureExec()
 	pluginPath, err := c.exec.FindInPath(net.Network.Type, c.Path)
 	if err != nil {

diff --git a/libcni/api_test.go b/libcni/api_test.go
@@ -176,7 +176,7 @@ var _ = Describe("Invoking plugins", func() {
 			pluginConfig  []byte
 			cniConfig     *libcni.CNIConfig
 			runtimeConfig *libcni.RuntimeConf
-			netConfig     *libcni.NetworkConfig
+			netConfig     *libcni.PluginConfig
 			ctx           context.Context
 		)
 
@@ -295,7 +295,7 @@ var _ = Describe("Invoking plugins", func() {
 			debug         *noop_debug.Debug
 			pluginConfig  string
 			cniConfig     *libcni.CNIConfig
-			netConfig     *libcni.NetworkConfig
+			netConfig     *libcni.PluginConfig
 			runtimeConfig *libcni.RuntimeConf
 			ctx           context.Context
 
@@ -1625,7 +1625,7 @@ var _ = Describe("Invoking plugins", func() {
 			cniBinPath    string
 			pluginConfig  string
 			cniConfig     *libcni.CNIConfig
-			netConfig     *libcni.NetworkConfig
+			netConfig     *libcni.PluginConfig
 			runtimeConfig *libcni.RuntimeConf
 			netConfigList *libcni.NetworkConfigList
 		)
@@ -1798,7 +1798,7 @@ var _ = Describe("Invoking plugins", func() {
 			cniBinPath    string
 			pluginConfig  string
 			cniConfig     *libcni.CNIConfig
-			netConfig     *libcni.NetworkConfig
+			netConfig     *libcni.PluginConfig
 			runtimeConfig *libcni.RuntimeConf
 
 			ctx context.Context
@@ -1920,14 +1920,14 @@ var _ = Describe("Invoking plugins", func() {
 		Context("when the RuntimeConf is incomplete", func() {
 			var (
 				testRt          *libcni.RuntimeConf
-				testNetConf     *libcni.NetworkConfig
+				testNetConf     *libcni.PluginConfig
 				testNetConfList *libcni.NetworkConfigList
 			)
 
 			BeforeEach(func() {
 				testRt = &libcni.RuntimeConf{}
-				testNetConf = &libcni.NetworkConfig{
-					Network: &types.NetConf{},
+				testNetConf = &libcni.PluginConfig{
+					Network: &types.PluginConf{},
 				}
 				testNetConfList = &libcni.NetworkConfigList{}
 			})