Define Linux Network Devices

The proposed "netdevices" field provides a declarative way to
specify which host network devices should be moved into a container's
network namespace.

This approach is similar than the existing "devices" field used for block
devices but uses a dictionary keyed by the interface name instead.

The proposed scheme is based on the existing representation of network
device by the `struct net_device`
https://docs.kernel.org/networking/netdevices.html.

This proposal focuses solely on moving existing network devices into
the container namespace. It does not cover the complexities of
network configuration or network interface creation, emphasizing the
separation of device management and network configuration.

Signed-off-by: Antonio Ojea <[email protected]>

Author: aojea

config-linux.md

@@ -189,6 +189,44 @@ In addition to any devices configured with this setting, the runtime MUST also s
 * [`/dev/ptmx`][pts.4].
   A [bind-mount or symlink of the container's `/dev/pts/ptmx`][devpts].
 
+## <a name="configLinuxNetworkDevices" />Network Devices
+
+Linux network devices are entities that send and receive data packets.
+They are not represented as files in the /dev directory, unlike block devices, network devices are represented with the [`net_device`][net_device] data structure in the Linux kernel.
+Network devices can belong to only one network namespace and use a set of operations distinct from regular file operations. Examples of network devices include Ethernet cards, loopback devices, and virtual devices like bridges, VLANs, and MACVLANs.
+
+This schema focuses solely on moving existing network devices identified by name from the host network namespace into the container network namespace. It does not cover the complexities of network device creation or network configuration, such as IP address assignment, routing, and DNS setup.
+
+**`netDevices`** (object, OPTIONAL) set of network devices that MUST be made available in the container. The runtime is responsible for providing these devices; the underlying mechanism is implementation-defined.
+
+The runtime MUST check that is possible to move the network interface to the container namespace and MUST [generate an error](runtime.md#errors) if the check fails.
+
+The runtime MUST preserve the existing network interface attributes, like MTU, MAC and IP addresses, enabling users to preconfigure the interfaces.
+
+The runtime MUST set the network device state to "up" after moving it to the network namespace to allow the container to send and receive network traffic through that device.
+
+For proper container termination, the runtime must first set the device's state to "down" and then move it out of the namespace before the namespace is deleted. This ensures the device is inactive and avoids conflicts. If the container abnormally terminates and the runtime does not participate in the termination process, these steps might be skipped, and the kernel will handle the process, described in [network_namespaces(7)][net_namespaces.7] "When a network namespace is freed (i.e., when the last process in the namespace terminates), its physical network devices are moved back to the initial network namespace" . Notice that after deleting a network namespace, all its migratable network devices are moved to the default network namespace, but virtual devices (veth, macvlan, ...) are destroyed.
+
+The name of the network device is the entry key.
+Entry values are objects with the following properties:
+
+* **`name`** *(string, OPTIONAL)* - the name of the network device inside the container namespace. If not specified, the host name is used. The network device name is unique per network namespace, if an existing network device with the same name exists that rename operation will fail. The runtime MAY check that the name is unique before the rename operation.
+The runtime, when participating on the container termination, must revert back the original name to guarantee the idempotence of operations, so a container that moves an interface and renames it can be created and destroyed multiple times with the same result.
+
+### Example
+
+#### Moving a device with a renamed interface inside the container:
+
+```json
+"netDevices": {
+    "eth0" : {
+        "name": "container_eth0"
+    }
+}
+```
+
+This configuration will move the device named "eth0" from the host into the container's network namespace. Inside the container, the device will be named "container_eth0".
+
 ## <a name="configLinuxControlGroups" />Control groups
 
 Also known as cgroups, they are used to restrict resource usage for a container and handle device access.
@@ -975,6 +1013,8 @@ subset of the available options.
 [mknod.1]: https://man7.org/linux/man-pages/man1/mknod.1.html
 [mknod.2]: https://man7.org/linux/man-pages/man2/mknod.2.html
 [namespaces.7_2]: https://man7.org/linux/man-pages/man7/namespaces.7.html
+[net_device]: https://docs.kernel.org/networking/netdevices.html
+[net_namespaces.7]: https://man7.org/linux/man-pages/man7/network_namespaces.7.html
 [null.4]: https://man7.org/linux/man-pages/man4/null.4.html
 [personality.2]: https://man7.org/linux/man-pages/man2/personality.2.html
 [pts.4]: https://man7.org/linux/man-pages/man4/pts.4.html

features-linux.md

@@ -228,3 +228,17 @@ Irrelevant to the availability of Intel RDT on the host operating system.
   }
 }
 ```
+
+## <a name="linuxFeaturesNetDevices" />NetDevices
+
+**`netDevices`** (object, OPTIONAL) represents the runtime's implementation status of Linux network devices.
+
+* **`enabled`** (bool, OPTIONAL) represents whether the runtime supports the capability to move Linux network devices into the container's network namespace.
+
+### Example
+
+```json
+"netDevices": {
+  "enabled": true
+}
+```

schema/config-linux.json

@@ -9,6 +9,12 @@
                     "$ref": "defs-linux.json#/definitions/Device"
                 }
             },
+            "netDevices": {
+                "type": "object",
+                "additionalProperties": {
+                    "$ref": "defs-linux.json#/definitions/NetDevice"
+                }
+            },
             "uidMappings": {
                 "type": "array",
                 "items": {

schema/defs-linux.json

@@ -189,6 +189,14 @@
                 }
             }
         },
+        "NetDevice": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
         "weight": {
             "$ref": "defs.json#/definitions/uint16"
         },

schema/features-linux.json

@@ -110,6 +110,14 @@
                         }
                     }
                 }
+            },
+            "netDevices": {
+                "type": "object",
+                "properties": {
+                    "enabled": {
+                        "type": "boolean"
+                    }
+                }
             }
         }
     }

schema/test/config/bad/linux-netdevice.json

@@ -0,0 +1,13 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "netDevices": {
+            "eth0": {
+                "name": 23
+            }
+        }
+    }
+}

schema/test/config/good/linux-netdevice.json

@@ -0,0 +1,15 @@
+{
+    "ociVersion": "1.0.0",
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "netDevices": {
+            "eth0": {
+                "name": "container_eth0"
+            },
+            "ens4": {},
+            "ens5": {}
+        }
+    }
+}

schema/test/features/good/runc.json

@@ -182,6 +182,9 @@
         },
         "selinux": {
             "enabled": true
+        },
+        "netDevices": {
+            "enabled": true
         }
     },
     "annotations": {

specs-go/config.go

@@ -236,6 +236,8 @@ type Linux struct {
 	Namespaces []LinuxNamespace `json:"namespaces,omitempty"`
 	// Devices are a list of device nodes that are created for the container
 	Devices []LinuxDevice `json:"devices,omitempty"`
+	// NetDevices are key-value pairs, keyed by network device name on the host, moved to the container's network namespace.
+	NetDevices map[string]LinuxNetDevice `json:"netDevices,omitempty"`
 	// Seccomp specifies the seccomp security settings for the container.
 	Seccomp *LinuxSeccomp `json:"seccomp,omitempty"`
 	// RootfsPropagation is the rootfs mount propagation mode for the container.
@@ -491,6 +493,12 @@ type LinuxDevice struct {
 	GID *uint32 `json:"gid,omitempty"`
 }
 
+// LinuxNetDevice represents a single network device to be added to the container's network namespace
+type LinuxNetDevice struct {
+	// Name of the device in the container namespace
+	Name string `json:"name,omitempty"`
+}
+
 // LinuxDeviceCgroup represents a device rule for the devices specified to
 // the device controller
 type LinuxDeviceCgroup struct {

specs-go/features/features.go

@@ -48,6 +48,7 @@ type Linux struct {
 	Selinux         *Selinux         `json:"selinux,omitempty"`
 	IntelRdt        *IntelRdt        `json:"intelRdt,omitempty"`
 	MountExtensions *MountExtensions `json:"mountExtensions,omitempty"`
+	NetDevices      *NetDevices      `json:"netDevices,omitempty"`
 }
 
 // Cgroup represents the "cgroup" field.
@@ -143,3 +144,10 @@ type IDMap struct {
 	// Nil value means "unknown", not "false".
 	Enabled *bool `json:"enabled,omitempty"`
 }
+
+// NetDevices represents the "netDevices" field.
+type NetDevices struct {
+	// Enabled is true if network devices support is compiled in.
+	// Nil value means "unknown", not "false".
+	Enabled *bool `json:"enabled,omitempty"`
+}