Define Linux Network Devices #1271

aojea · 2024-11-07T11:28:39Z

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.

Fixes: #1239

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]>

aojea · 2024-11-07T11:29:28Z

/assign @samuelkarp

config-linux.md

AkihiroSuda · 2024-11-07T20:29:28Z

config-linux.md

+
+**`netdevices`** (object, OPTIONAL) set of network devices that MUST be available in the container. The runtime MAY supply them however it likes.
+
+The name of the network device is the entry key.


Does the map order matter? If so, implementation can be complicated for Go

the linux kernel guarantees the uniqueness of the name in the runtime namespace, so a set is ok. Order is not important , each network device should be independent of each other ...

Should we recommend a runtime performs a uniqueness check as well?

Uniqueness inside container should be checked, e.g. that rename operation was successful

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

AkihiroSuda · 2024-11-07T23:44:26Z

https://github.com/opencontainers/runtime-spec/blob/main/features.md should be updated too

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

aojea · 2024-11-12T12:29:47Z

https://github.com/opencontainers/runtime-spec/blob/main/features.md should be updated too

updated and addressed the comments

samuelkarp · 2024-11-12T21:35:53Z

config-linux.md

+
+**`netdevices`** (object, OPTIONAL) set of network devices that MUST be available in the container. The runtime MAY supply them however it likes.
+
+The name of the network device is the entry key.


Should we recommend a runtime performs a uniqueness check as well?

samuelkarp · 2024-11-12T21:38:51Z

schema/config-linux.json

@@ -294,4 +300,4 @@
            }
        }
    }
-}
+}


nit: newline missing at the end

samuelkarp · 2024-11-12T21:39:26Z

schema/defs-linux.json

@@ -349,4 +366,4 @@
            ]
        }
    }
-}
+}


nit: newline missing at the end

samuelkarp · 2024-11-12T21:39:58Z

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

+            }
+        }
+    }
+}


nit: newline missing at the end

samuelkarp · 2024-11-12T21:40:04Z

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

+            }
+        }
+    }
+}


nit: newline missing at the end

aojea · 2024-11-12T21:52:30Z

AI @aojea (document the cleanup and destroy of the network interfaces)

askervin · 2024-11-12T22:22:24Z

config-linux.md

+
+```json
+
+"netDevices": [


In this and the next example netDevices looks like "array of objects" rather than "object" as specified.

ups, yes, carrying over from a previous attempt, thanks for catching it

samuelkarp · 2024-11-12T22:23:45Z

From the in-person discussion today:

Net device lifecycle should follow the network namespace lifecycle
@aojea will follow up to determine whether any cleanup actions need to be taken by the OCI runtime on a container being deleted
@kad was concerned about restarts and error handling
Should we prohibit the new netdev addition to an existing netns? IOW only allow this for containers where a new netns is created? What about containers where the root netns is used?

utam0k · 2024-11-12T22:25:13Z

config-linux.md

+
+This schema focuses solely on moving existing network devices identified by name into the container 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 available in the container. The runtime is responsible for providing these devices; the underlying mechanism is implementation-defined.


This spec said "MUST" but, I think it can't do it in the rootless container because the rootless container doesn't have CAP_NET_ADMIN, right?

I'm not sure we should take care of the rootless container.

Could be an error in the case of a rootless container, if the runtime is not able to satisfy the MUST condition.

Could be an error in the case of a rootless container, if the runtime is not able to satisfy the MUST condition.

+1 but It'd be better to clarify it in the spec.

kad · 2024-11-12T22:29:13Z

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

+                "name": "container_eth0"
+            },
+            "ens4": {
+                "address": "10.0.0.10",


good and bad examples with IPv6 address might be good to add.

utam0k · 2024-11-12T22:30:27Z

config-linux.md

+
+### Example
+
+#### Moving a device with a renamed interface inside the container:


Why do we need to take care of the renaming case?

because the name is unique, and the container already will have a network interface attached by the network configuration operation (CNI, libnetwork, netvark, ...) so this offers the capability to the user to avoid this collision

aojea requested review from AkihiroSuda, crosbymichael, cyphar, dqminh, giuseppe, hqhq, kolyshkin, mrunalp, thaJeztah, tianon and utam0k as code owners November 7, 2024 11:28

AkihiroSuda reviewed Nov 7, 2024

View reviewed changes

config-linux.md Outdated Show resolved Hide resolved

AkihiroSuda reviewed Nov 7, 2024

View reviewed changes

config-linux.md Outdated Show resolved Hide resolved

AkihiroSuda reviewed Nov 7, 2024

View reviewed changes

config-linux.md Outdated Show resolved Hide resolved

AkihiroSuda reviewed Nov 7, 2024

View reviewed changes

define string representation of IP addresses

5541940

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

clarify runtime implementation for netdvices

dcb9f52

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

aojea force-pushed the network-devices branch from 931e8b8 to 51e5104 Compare November 12, 2024 12:21

aojea added 2 commits November 12, 2024 12:26

replace netdevices with netDevices

6a8be5d

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

add feature for network devices

3a666eb

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

aojea force-pushed the network-devices branch from 51e5104 to 3a666eb Compare November 12, 2024 12:26

samuelkarp reviewed Nov 12, 2024

View reviewed changes

askervin reviewed Nov 12, 2024

View reviewed changes

utam0k reviewed Nov 12, 2024

View reviewed changes

kad reviewed Nov 12, 2024

View reviewed changes

utam0k reviewed Nov 12, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Define Linux Network Devices #1271

Define Linux Network Devices #1271

aojea commented Nov 7, 2024

aojea commented Nov 7, 2024

AkihiroSuda Nov 7, 2024 •

edited

Loading

aojea Nov 7, 2024

samuelkarp Nov 12, 2024

kad Nov 12, 2024

AkihiroSuda commented Nov 7, 2024

aojea commented Nov 12, 2024

samuelkarp Nov 12, 2024

samuelkarp Nov 12, 2024

samuelkarp Nov 12, 2024

samuelkarp Nov 12, 2024

samuelkarp Nov 12, 2024

aojea commented Nov 12, 2024

askervin Nov 12, 2024

aojea Nov 15, 2024

samuelkarp commented Nov 12, 2024

utam0k Nov 12, 2024

utam0k Nov 12, 2024

samuelkarp Nov 12, 2024

utam0k Nov 12, 2024

kad Nov 12, 2024

utam0k Nov 12, 2024

aojea Nov 12, 2024


		`netdevices` (object, OPTIONAL) set of network devices that MUST be available in the container. The runtime MAY supply them however it likes.

		The name of the network device is the entry key.

@@ @@ -294,4 +300,4 @@ @@
                           }
                       }
                   }
-              }
+              }

@@ @@ -349,4 +366,4 @@ @@
                           ]
                       }
                   }
-              }
+              }


		This schema focuses solely on moving existing network devices identified by name into the container 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 available in the container. The runtime is responsible for providing these devices; the underlying mechanism is implementation-defined.


		### Example

		#### Moving a device with a renamed interface inside the container:


		```json

		"netDevices": [

Define Linux Network Devices #1271

Are you sure you want to change the base?

Define Linux Network Devices #1271

Conversation

aojea commented Nov 7, 2024

aojea commented Nov 7, 2024

AkihiroSuda Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AkihiroSuda commented Nov 7, 2024

aojea commented Nov 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aojea commented Nov 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

samuelkarp commented Nov 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AkihiroSuda Nov 7, 2024 •

edited

Loading