Add Motivation section and rename CNI struct to CNIConfig

* Add Motivation section for the device configuration API * Rename CNI struct to CNIConfig in the API * Remove generated code and codegen * Add note for the CNI config validation Signed-off-by: Lionel Jouin <[email protected]>
kubernetes-sigs · Jan 7, 2025 · 99bfb5f · 99bfb5f
1 parent 19eeb41
commit 99bfb5f
Show file tree

Hide file tree

Showing 11 changed files with 20 additions and 380 deletions.
diff --git a/Makefile b/Makefile
diff --git a/apis/v1alpha1/doc.go b/apis/v1alpha1/doc.go
@@ -16,7 +16,4 @@ limitations under the License.
 
 // Package v1alpha contains API Schema definitions for the cni.dra.networking.x-k8s.io
 // API group.
-//
-// +k8s:deepcopy-gen=package
-// +groupName=cni.dra.networking.x-k8s.io
 package v1alpha1
diff --git a/apis/v1alpha1/types.go b/apis/v1alpha1/types.go
@@ -20,11 +20,8 @@ import (
 	"k8s.io/apimachinery/pkg/runtime"
 )
 
-// +genclient
-// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
-
-// CNI is the object used in ResourceClaim.specs.devices.config
-type CNI struct {
+// CNIConfig is the object used in ResourceClaim.specs.devices.config opaque parameters.
+type CNIConfig struct {
 	metav1.TypeMeta `json:",inline"`
 
 	// IfName represents the name of the network interface requested.

diff --git a/apis/v1alpha1/zz_generated.deepcopy.go b/apis/v1alpha1/zz_generated.deepcopy.go
diff --git a/apis/v1alpha1/zz_generated.register.go b/apis/v1alpha1/zz_generated.register.go
diff --git a/docs/design/device-configuration-api.md b/docs/design/device-configuration-api.md
@@ -6,9 +6,17 @@ This document defines the API and mechanism to configure and manage CNI network
 
 The design aims to support all possible functionalities the Container Network Interface (CNI) project offers while ensuring compliance with its specifications.
 
+## Motivation
+
+Configuring and reporting network interfaces in Kubernetes currently lacks a standardized and native approach. Existing solutions such as [Multus](https://github.com/k8snetworkplumbingwg/multus-cni) address this challenge by relying on CNI, custom resources, and pod annotations. However, these solutions do not provide a fully integrated and standardized method within Kubernetes. The Device Configuration API of the CNI-DRA-Driver aims to fill this gap by leveraging the CNI API together with the DRA API to provide a modern and more Kubernetes integrated mechanism to configure and report network interfaces on pods.
+
+This document defines the configuration API for configuring network interfaces on pods using CNI and outlines the behaviors and interactions during the operations (e.g. `ADD` and `DEL`) on the network interfaces and pods. The capabilities and limitations of this approach are also highlighted to ensure a clear understanding of its scope.
+
+Additionally, this solution will serve as a reference implementation for the [Multi-Network](https://github.com/kubernetes-sigs/multi-network) project and for the [KEP-4817 (Resource Claim Status With Possible Standardized Network Interface Data)](https://github.com/kubernetes/enhancements/blob/master/keps/sig-node/4817-resource-claim-device-status/README.md).
+
 ## Design
 
-A new API with the Kind `CNI` will be introduced under the `cni.networking.x-k8s.io` Group. This API will be providing the CNI configuration along with necessary parameters and optional fields for invoking CNI plugins. The configuration data specified in the `opaque.parameters` will be reflected in the ResourceClaim status by Kubernetes. This reported status will provide the necessary details for executing CNI operations such as `ADD` on pod creation and `DEL` on pod deletion which will enable seamless lifecycle management.
+A new API with the Kind `CNIConfig` will be introduced under the `cni.networking.x-k8s.io` Group. This API will be providing the CNI configuration along with necessary parameters and optional fields for invoking CNI plugins. The configuration data specified in the `opaque.parameters` will be reflected in the ResourceClaim status by Kubernetes. This reported status will provide the necessary details for executing CNI operations such as `ADD` on pod creation and `DEL` on pod deletion which will enable seamless lifecycle management.
 
 Each ResourceClaim can be claimed by at most one pod as the ResourceClaim status represents network interfaces configured specifically for that pod. Since the devices configured via CNI are pod scoped rather than container scoped, the ResourceClaims must be associated at the pod level.
 
@@ -18,13 +26,13 @@ To support scenarios where multiple network interfaces are required, a ResourceC
 
 ### Configuration
 
-This API defines the parameters and CNI configuration required to invoke CNI plugins. The CNI object encapsulates two fields:
+This API defines the parameters and CNI configuration required to invoke CNI plugins. The `CNIConfig` object encapsulates two fields:
 * `IfName`: specifies the name of the network interface to be configured.
 * `Config`: contains the CNI configuration represented as a generic type `runtime.RawExtension`.
 
 ```golang
-// CNI is the object used in ResourceClaim.specs.devices.config
-type CNI struct {
+// CNIConfig is the object used in ResourceClaim.specs.devices.config opaque parameters.
+type CNIConfig struct {
 	metav1.TypeMeta `json:",inline"`
 
 	// IfName represents the name of the network interface requested.
@@ -35,7 +43,7 @@ type CNI struct {
 }
 ```
 
-Requests using the device class `cni.networking.x-k8s.io` must include exactly one configuration attached to it, so each configuration must point to a single request (one-to-one relationship between the config (CNI object) and the request). This configuration must specify the driver name `cni.dra.networking.x-k8s.io` and the corresponding CNI object in the `opaque.parameters` field. 
+Requests using the device class `cni.networking.x-k8s.io` must include exactly one configuration attached to it, so each configuration must point to a single request (one-to-one relationship between the config (CNI object) and the request). This configuration must specify the driver name `cni.dra.networking.x-k8s.io` and the corresponding `CNIConfig` object in the `opaque.parameters` field. 
 
 Each request will configure one network interface in the pod.
 
@@ -201,8 +209,9 @@ ResourceClaim validation:
 * A ResourceClaim utilizing the device class `cni.networking.x-k8s.io` must be claimed by one and only one pod.
 
 Opaque Parameter validation:
-* All properties in the CNI object must be valid (e.g. `IfName`).
+* All properties in the `CNIConfig` object must be valid (e.g. `IfName`).
 * The CNI config must follow correct syntax and semantics.
+    * Note: A mechanism is first required from the CNI project to achieve this validation (see [containernetworking/cni#1132](https://github.com/containernetworking/cni/issues/1132)).
 * The validation does not check if the CNI plugin exists (This responsibility is on the scheduler)
 
 ## Related Resources

diff --git a/go.mod b/go.mod
@@ -2,53 +2,25 @@ module sigs.k8s.io/cni-dra-driver
 
 go 1.23
 
-require (
-	k8s.io/apimachinery v0.31.4
-	k8s.io/code-generator v0.31.4
-	sigs.k8s.io/controller-tools v0.16.5
-)
+require k8s.io/apimachinery v0.31.4
 
 require (
-	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
-	github.com/fatih/color v1.18.0 // indirect
 	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
-	github.com/go-openapi/jsonpointer v0.19.6 // indirect
-	github.com/go-openapi/jsonreference v0.20.2 // indirect
-	github.com/go-openapi/swag v0.22.4 // indirect
-	github.com/gobuffalo/flect v1.0.3 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/protobuf v1.5.4 // indirect
-	github.com/google/gnostic-models v0.6.8 // indirect
 	github.com/google/gofuzz v1.2.0 // indirect
-	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/mailru/easyjson v0.7.7 // indirect
-	github.com/mattn/go-colorable v0.1.13 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/kr/text v0.2.0 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/spf13/cobra v1.8.1 // indirect
-	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
-	golang.org/x/mod v0.21.0 // indirect
 	golang.org/x/net v0.30.0 // indirect
-	golang.org/x/sync v0.8.0 // indirect
-	golang.org/x/sys v0.26.0 // indirect
 	golang.org/x/text v0.19.0 // indirect
-	golang.org/x/tools v0.26.0 // indirect
-	google.golang.org/protobuf v1.34.2 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/api v0.31.2 // indirect
-	k8s.io/apiextensions-apiserver v0.31.2 // indirect
-	k8s.io/gengo/v2 v2.0.0-20240228010128-51d4e06bde70 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect
-	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
 	k8s.io/utils v0.0.0-20240711033017-18e509b52bc8 // indirect
 	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
-	sigs.k8s.io/yaml v1.4.0 // indirect
 )