feat: add permanent hardware addr to device selectors

This should fix the problem of including bond members by MAC address when MAC address changes as the link becomes part of the bond. Signed-off-by: Andrey Smirnov <andrey.smirnov@siderolabs.com>
siderolabs · Nov 18, 2024 · fd713e4 · fd713e4
1 parent d55a96e
commit fd713e4
Show file tree

Hide file tree

Showing 11 changed files with 82 additions and 36 deletions.
diff --git a/hack/release.toml b/hack/release.toml
@@ -81,6 +81,13 @@ Talos will never fall back to the default registry if endpoints are configured,
 
 In Talos 1.9 this was fixed, so that by default an upstream registry is used as a fallback in all cases, while new registry mirror
 configuration option `.skipFallback` can be used to disable this behavior both for Talos and CRI plugin.
+"""
+
+    [notes.device-selectors]
+        title = "Device Selectors"
+        description = """\
+Talos now supports matching on permanent hardware (MAC) address of the network interfaces.
+This is specifically useful to match bond members, as they change their hardware addresses when they become part of the bond.
 """
 
 [make_deps]

diff --git a/internal/app/machined/pkg/controllers/network/device_config.go b/internal/app/machined/pkg/controllers/network/device_config.go
@@ -214,6 +214,7 @@ func (ctrl *DeviceConfigController) selectDevices(selector talosconfig.NetworkDe
 
 		for _, pair := range [][]string{
 			{selector.HardwareAddress(), linkStatusSpec.HardwareAddr.String()},
+			{selector.PermanentAddress(), linkStatusSpec.PermanentAddr.String()},
 			{selector.PCIID(), linkStatusSpec.PCIID},
 			{selector.KernelDriver(), linkStatusSpec.Driver},
 			{selector.Bus(), linkStatusSpec.BusPath},

diff --git a/internal/app/machined/pkg/controllers/network/device_config_test.go b/internal/app/machined/pkg/controllers/network/device_config_test.go
@@ -174,10 +174,10 @@ func (suite *DeviceConfigSpecSuite) TestBondSelectors() {
 							BondMode: "balance-rr",
 							BondDeviceSelectors: []v1alpha1.NetworkDeviceSelector{
 								{
-									NetworkDeviceHardwareAddress: "00:*",
+									NetworkDevicePermanentAddress: "00:*",
 								},
 								{
-									NetworkDeviceHardwareAddress: "01:*",
+									NetworkDevicePermanentAddress: "01:*",
 								},
 							},
 						},
@@ -226,7 +226,7 @@ func (suite *DeviceConfigSpecSuite) TestBondSelectors() {
 		suite.Require().NoError(err)
 
 		status := network.NewLinkStatus(network.NamespaceName, link.name)
-		status.TypedSpec().HardwareAddr = nethelpers.HardwareAddr(hwaddr)
+		status.TypedSpec().PermanentAddr = nethelpers.HardwareAddr(hwaddr)
 		suite.Require().NoError(suite.State().Create(suite.Ctx(), status))
 	}
 

diff --git a/pkg/machinery/config/config/machine.go b/pkg/machinery/config/config/machine.go
@@ -318,6 +318,7 @@ type KubeSpanFilters interface {
 type NetworkDeviceSelector interface {
 	Bus() string
 	HardwareAddress() string
+	PermanentAddress() string
 	PCIID() string
 	KernelDriver() string
 	Physical() *bool

diff --git a/pkg/machinery/config/schemas/config.schema.json b/pkg/machinery/config/schemas/config.schema.json
@@ -3008,9 +3008,16 @@
         "hardwareAddr": {
           "type": "string",
           "title": "hardwareAddr",
-          "description": "Device hardware address, supports matching by wildcard.\n",
-          "markdownDescription": "Device hardware address, supports matching by wildcard.",
-          "x-intellij-html-description": "\u003cp\u003eDevice hardware address, supports matching by wildcard.\u003c/p\u003e\n"
+          "description": "Device hardware (MAC) address, supports matching by wildcard.\n",
+          "markdownDescription": "Device hardware (MAC) address, supports matching by wildcard.",
+          "x-intellij-html-description": "\u003cp\u003eDevice hardware (MAC) address, supports matching by wildcard.\u003c/p\u003e\n"
+        },
+        "permanentAddr": {
+          "type": "string",
+          "title": "permanentAddr",
+          "description": "Device permanent hardware address, supports matching by wildcard.\nThe permanent address doesn’t change when the link is enslaved to a bond,\nso it’s recommended to use this field for bond members.\n",
+          "markdownDescription": "Device permanent hardware address, supports matching by wildcard.\nThe permanent address doesn't change when the link is enslaved to a bond,\nso it's recommended to use this field for bond members.",
+          "x-intellij-html-description": "\u003cp\u003eDevice permanent hardware address, supports matching by wildcard.\nThe permanent address doesn\u0026rsquo;t change when the link is enslaved to a bond,\nso it\u0026rsquo;s recommended to use this field for bond members.\u003c/p\u003e\n"
         },
         "pciID": {
           "type": "string",

diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_provider.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_provider.go
@@ -851,6 +851,11 @@ func (s *NetworkDeviceSelector) HardwareAddress() string {
 	return s.NetworkDeviceHardwareAddress
 }
 
+// PermanentAddress implements config.NetworkDeviceSelector interface.
+func (s *NetworkDeviceSelector) PermanentAddress() string {
+	return s.NetworkDevicePermanentAddress
+}
+
 // PCIID implements config.NetworkDeviceSelector interface.
 func (s *NetworkDeviceSelector) PCIID() string {
 	return s.NetworkDevicePCIID

diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types.go
@@ -2324,8 +2324,13 @@ type KubeSpanFilters struct {
 type NetworkDeviceSelector struct {
 	// description: PCI, USB bus prefix, supports matching by wildcard.
 	NetworkDeviceBus string `yaml:"busPath,omitempty"`
-	// description: Device hardware address, supports matching by wildcard.
+	// description: Device hardware (MAC) address, supports matching by wildcard.
 	NetworkDeviceHardwareAddress string `yaml:"hardwareAddr,omitempty"`
+	// description: |
+	//    Device permanent hardware address, supports matching by wildcard.
+	//    The permanent address doesn't change when the link is enslaved to a bond,
+	//    so it's recommended to use this field for bond members.
+	NetworkDevicePermanentAddress string `yaml:"permanentAddr,omitempty"`
 	// description: PCI ID (vendor ID, product ID), supports matching by wildcard.
 	NetworkDevicePCIID string `yaml:"pciID,omitempty"`
 	// description: Kernel driver, supports matching by wildcard.

diff --git a/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go b/pkg/machinery/config/types/v1alpha1/v1alpha1_types_doc.go
diff --git a/website/content/v1.9/reference/configuration/v1alpha1/config.md b/website/content/v1.9/reference/configuration/v1alpha1/config.md
@@ -172,12 +172,12 @@ network:
           #     busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
           # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
           # deviceSelector:
-          #     hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+          #     hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
           #     driver: virtio # Kernel driver, supports matching by wildcard.
           # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
           # deviceSelector:
           #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-          #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+          #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
           #       driver: virtio # Kernel driver, supports matching by wildcard.
 
           # # Bond specific options.
@@ -189,7 +189,7 @@ network:
           #     # Picks a network device using the selector.
           #     deviceSelectors:
           #         - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-          #         - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+          #         - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
           #           driver: virtio # Kernel driver, supports matching by wildcard.
           #     mode: 802.3ad # A bond option.
           #     lacpRate: fast # A bond option.
@@ -747,12 +747,12 @@ machine:
               #     busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
               # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
               # deviceSelector:
-              #     hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #     hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #     driver: virtio # Kernel driver, supports matching by wildcard.
               # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
               # deviceSelector:
               #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-              #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #       driver: virtio # Kernel driver, supports matching by wildcard.
 
               # # Bond specific options.
@@ -764,7 +764,7 @@ machine:
               #     # Picks a network device using the selector.
               #     deviceSelectors:
               #         - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-              #         - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #         - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #           driver: virtio # Kernel driver, supports matching by wildcard.
               #     mode: 802.3ad # A bond option.
               #     lacpRate: fast # A bond option.
@@ -862,12 +862,12 @@ interfaces:
       #     busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
       # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
       # deviceSelector:
-      #     hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+      #     hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
       #     driver: virtio # Kernel driver, supports matching by wildcard.
       # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
       # deviceSelector:
       #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-      #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+      #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
       #       driver: virtio # Kernel driver, supports matching by wildcard.
 
       # # Bond specific options.
@@ -879,7 +879,7 @@ interfaces:
       #     # Picks a network device using the selector.
       #     deviceSelectors:
       #         - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-      #         - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+      #         - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
       #           driver: virtio # Kernel driver, supports matching by wildcard.
       #     mode: 802.3ad # A bond option.
       #     lacpRate: fast # A bond option.
@@ -986,12 +986,12 @@ machine:
               #     busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
               # # select a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
               # deviceSelector:
-              #     hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #     hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #     driver: virtio # Kernel driver, supports matching by wildcard.
               # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
               # deviceSelector:
               #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-              #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #       driver: virtio # Kernel driver, supports matching by wildcard.
 
               # # Bond specific options.
@@ -1003,7 +1003,7 @@ machine:
               #     # Picks a network device using the selector.
               #     deviceSelectors:
               #         - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-              #         - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+              #         - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
               #           driver: virtio # Kernel driver, supports matching by wildcard.
               #     mode: 802.3ad # A bond option.
               #     lacpRate: fast # A bond option.
@@ -1072,7 +1072,7 @@ deviceSelector:
     busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
 {{< /highlight >}}{{< highlight yaml >}}
 deviceSelector:
-    hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+    hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
     driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}</details> | |
 |`addresses` |[]string |<details><summary>Assigns static IP addresses to the interface.</summary>An address can be specified either in proper CIDR notation or as a standalone address (netmask of all ones is assumed).</details> <details><summary>Show example(s)</summary>{{< highlight yaml >}}
@@ -1101,7 +1101,7 @@ bond:
     # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
     # deviceSelectors:
     #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-    #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+    #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
     #       driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}</details> | |
 |`bridge` |<a href="#Config.machine.network.interfaces..bridge">Bridge</a> |Bridge specific options. <details><summary>Show example(s)</summary>{{< highlight yaml >}}
@@ -1179,7 +1179,7 @@ machine:
     network:
         interfaces:
             - deviceSelector:
-                hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+                hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
                 driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}
 
@@ -1189,15 +1189,16 @@ machine:
         interfaces:
             - deviceSelector:
                 - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-                - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+                - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
                   driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}
 
 
 | Field | Type | Description | Value(s) |
 |-------|------|-------------|----------|
 |`busPath` |string |PCI, USB bus prefix, supports matching by wildcard.  | |
-|`hardwareAddr` |string |Device hardware address, supports matching by wildcard.  | |
+|`hardwareAddr` |string |Device hardware (MAC) address, supports matching by wildcard.  | |
+|`permanentAddr` |string |<details><summary>Device permanent hardware address, supports matching by wildcard.</summary>The permanent address doesn't change when the link is enslaved to a bond,<br />so it's recommended to use this field for bond members.</details>  | |
 |`pciID` |string |PCI ID (vendor ID, product ID), supports matching by wildcard.  | |
 |`driver` |string |Kernel driver, supports matching by wildcard.  | |
 |`physical` |bool |Select only physical devices.  | |
@@ -1261,7 +1262,7 @@ machine:
                 # # select a device with bus prefix 00:*, a device with mac address matching `*:f0:ab` and `virtio` kernel driver.
                 # deviceSelectors:
                 #     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-                #     - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+                #     - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
                 #       driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}
 
@@ -1272,7 +1273,7 @@ machine:
 |`deviceSelectors` |<a href="#Config.machine.network.interfaces..bond.deviceSelectors.">[]NetworkDeviceSelector</a> |<details><summary>Picks a network device using the selector.</summary>Mutually exclusive with `interfaces`.<br />Supports partial match using wildcard syntax.</details> <details><summary>Show example(s)</summary>{{< highlight yaml >}}
 deviceSelectors:
     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-    - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+    - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
       driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}</details> | |
 |`arpIPTarget` |[]string |<details><summary>A bond option.</summary>Please see the official kernel documentation.<br />Not supported at the moment.</details>  | |
@@ -1326,7 +1327,7 @@ machine:
         interfaces:
             - bond:
                 deviceSelectors:
-                    hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+                    hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
                     driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}
 
@@ -1337,15 +1338,16 @@ machine:
             - bond:
                 deviceSelectors:
                     - busPath: 00:* # PCI, USB bus prefix, supports matching by wildcard.
-                    - hardwareAddr: '*:f0:ab' # Device hardware address, supports matching by wildcard.
+                    - hardwareAddr: '*:f0:ab' # Device hardware (MAC) address, supports matching by wildcard.
                       driver: virtio # Kernel driver, supports matching by wildcard.
 {{< /highlight >}}
 
 
 | Field | Type | Description | Value(s) |
 |-------|------|-------------|----------|
 |`busPath` |string |PCI, USB bus prefix, supports matching by wildcard.  | |
-|`hardwareAddr` |string |Device hardware address, supports matching by wildcard.  | |
+|`hardwareAddr` |string |Device hardware (MAC) address, supports matching by wildcard.  | |
+|`permanentAddr` |string |<details><summary>Device permanent hardware address, supports matching by wildcard.</summary>The permanent address doesn't change when the link is enslaved to a bond,<br />so it's recommended to use this field for bond members.</details>  | |
 |`pciID` |string |PCI ID (vendor ID, product ID), supports matching by wildcard.  | |
 |`driver` |string |Kernel driver, supports matching by wildcard.  | |
 |`physical` |bool |Select only physical devices.  | |