From 90fe7adbee4bd8dc86735dfc421021c878dda2b8 Mon Sep 17 00:00:00 2001 From: Renuka Devi Rajendran Date: Mon, 13 Jul 2026 11:32:01 -0700 Subject: [PATCH 1/4] Add note for host network config with multiple intfs in same subnet Signed-off-by: Renuka Devi Rajendran --- docs/networking/hostnetworkconfig.md | 16 ++++++++++++++++ .../version-v1.8/networking/hostnetworkconfig.md | 16 ++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/docs/networking/hostnetworkconfig.md b/docs/networking/hostnetworkconfig.md index 83330c9f38..d4566e4c1b 100644 --- a/docs/networking/hostnetworkconfig.md +++ b/docs/networking/hostnetworkconfig.md @@ -317,6 +317,22 @@ Delete the config using the following command: `kubectl delete hostnetworkconfig cn1-vlan2012-dhcp`. +:::caution + +If a node has multiple host interfaces, do not connect them to the same VLAN or subnet. + +VLAN interfaces under a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issue: +- **DHCP response misrouting**: When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This occurs because the DHCP `OFFER` packets can be delivered to `mgmt-br` instead of `mgmt-br.1`. + +Configuring multiple interfaces in the same VLAN and subnet can result in ambiguous routing behavior. +- **Ambiguous kernel routing**: Linux typically installs a single connected route for a subnet. When multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended path. + +For example, if a host network on cluster network `cn1` uses VLAN `2017` and receives subnet `192.168.0.0/24`, while another host network on cluster network `cn2` is also configured with VLAN `2017` and receives the same subnet 192.168.0.0/24, the kernel will install the connected route for 192.168.0.0/24 via only one interface (the latest configured). As a result, traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. + +This restriction applies to interfaces configured both manually on the host and through `HostNetwork` configurations. + +::: + ### Limitations - Only tagged VLANs with a VLAN ID of 1–4094 are supported. diff --git a/versioned_docs/version-v1.8/networking/hostnetworkconfig.md b/versioned_docs/version-v1.8/networking/hostnetworkconfig.md index 83330c9f38..d4566e4c1b 100644 --- a/versioned_docs/version-v1.8/networking/hostnetworkconfig.md +++ b/versioned_docs/version-v1.8/networking/hostnetworkconfig.md @@ -317,6 +317,22 @@ Delete the config using the following command: `kubectl delete hostnetworkconfig cn1-vlan2012-dhcp`. +:::caution + +If a node has multiple host interfaces, do not connect them to the same VLAN or subnet. + +VLAN interfaces under a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issue: +- **DHCP response misrouting**: When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This occurs because the DHCP `OFFER` packets can be delivered to `mgmt-br` instead of `mgmt-br.1`. + +Configuring multiple interfaces in the same VLAN and subnet can result in ambiguous routing behavior. +- **Ambiguous kernel routing**: Linux typically installs a single connected route for a subnet. When multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended path. + +For example, if a host network on cluster network `cn1` uses VLAN `2017` and receives subnet `192.168.0.0/24`, while another host network on cluster network `cn2` is also configured with VLAN `2017` and receives the same subnet 192.168.0.0/24, the kernel will install the connected route for 192.168.0.0/24 via only one interface (the latest configured). As a result, traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. + +This restriction applies to interfaces configured both manually on the host and through `HostNetwork` configurations. + +::: + ### Limitations - Only tagged VLANs with a VLAN ID of 1–4094 are supported. From 43c985904040a8c24d20cf16c4b53e714ad8a2c9 Mon Sep 17 00:00:00 2001 From: Renuka Devi Rajendran Date: Wed, 15 Jul 2026 08:30:15 -0700 Subject: [PATCH 2/4] Update docs/networking/hostnetworkconfig.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran --- docs/networking/hostnetworkconfig.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/networking/hostnetworkconfig.md b/docs/networking/hostnetworkconfig.md index d4566e4c1b..859b72246e 100644 --- a/docs/networking/hostnetworkconfig.md +++ b/docs/networking/hostnetworkconfig.md @@ -319,7 +319,7 @@ Delete the config using the following command: :::caution -If a node has multiple host interfaces, do not connect them to the same VLAN or subnet. +If a node has multiple host interfaces, do not attach them to the same VLAN or subnet. This restriction applies to interfaces configured manually on the host and those configured through `HostNetwork` configurations. VLAN interfaces under a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issue: - **DHCP response misrouting**: When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This occurs because the DHCP `OFFER` packets can be delivered to `mgmt-br` instead of `mgmt-br.1`. From 0eacd33883e34c20b66dc47db545e245bd2b19e3 Mon Sep 17 00:00:00 2001 From: Renuka Devi Rajendran Date: Wed, 15 Jul 2026 08:30:35 -0700 Subject: [PATCH 3/4] Update docs/networking/hostnetworkconfig.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran --- docs/networking/hostnetworkconfig.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/networking/hostnetworkconfig.md b/docs/networking/hostnetworkconfig.md index 859b72246e..02e4f27948 100644 --- a/docs/networking/hostnetworkconfig.md +++ b/docs/networking/hostnetworkconfig.md @@ -321,8 +321,11 @@ Delete the config using the following command: If a node has multiple host interfaces, do not attach them to the same VLAN or subnet. This restriction applies to interfaces configured manually on the host and those configured through `HostNetwork` configurations. -VLAN interfaces under a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issue: -- **DHCP response misrouting**: When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This occurs because the DHCP `OFFER` packets can be delivered to `mgmt-br` instead of `mgmt-br.1`. +**DHCP Response Misrouting** + +VLAN interfaces used in a cluster network are derived from the same underlying bridge and consequently share the same MAC address. This shared MAC address can cause DHCP response misrouting. + +When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be incorrectly associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an active IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This failure occurs because the DHCP `OFFER` packets are delivered to `mgmt-br` instead of `mgmt-br.1`. Configuring multiple interfaces in the same VLAN and subnet can result in ambiguous routing behavior. - **Ambiguous kernel routing**: Linux typically installs a single connected route for a subnet. When multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended path. From f727a6448f99640fc3e8de4035c4e861b04240a5 Mon Sep 17 00:00:00 2001 From: Renuka Devi Rajendran Date: Wed, 15 Jul 2026 08:30:54 -0700 Subject: [PATCH 4/4] Update docs/networking/hostnetworkconfig.md Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran --- docs/networking/hostnetworkconfig.md | 7 +++---- .../version-v1.8/networking/hostnetworkconfig.md | 16 +++++++++------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/networking/hostnetworkconfig.md b/docs/networking/hostnetworkconfig.md index 02e4f27948..b33d2bea0e 100644 --- a/docs/networking/hostnetworkconfig.md +++ b/docs/networking/hostnetworkconfig.md @@ -327,12 +327,11 @@ VLAN interfaces used in a cluster network are derived from the same underlying b When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be incorrectly associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an active IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This failure occurs because the DHCP `OFFER` packets are delivered to `mgmt-br` instead of `mgmt-br.1`. -Configuring multiple interfaces in the same VLAN and subnet can result in ambiguous routing behavior. -- **Ambiguous kernel routing**: Linux typically installs a single connected route for a subnet. When multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended path. +**Ambiguous Routing Behavior** -For example, if a host network on cluster network `cn1` uses VLAN `2017` and receives subnet `192.168.0.0/24`, while another host network on cluster network `cn2` is also configured with VLAN `2017` and receives the same subnet 192.168.0.0/24, the kernel will install the connected route for 192.168.0.0/24 via only one interface (the latest configured). As a result, traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. +Additionally, configuring multiple interfaces in the same VLAN and subnet results in ambiguous routing. The Linux kernel typically installs a single connected route for a given subnet. If multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended physical path. -This restriction applies to interfaces configured both manually on the host and through `HostNetwork` configurations. +Example: Host networks on cluster networks `cn1` and `cn2` are both attached to VLAN `2017` and assigned the same subnet (`192.168.0.0/24`). Because both interfaces are in the same subnet, the Linux kernel will install the connected route for `192.168.0.0/24` via only one of those interfaces (typically the one configured last). Traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. ::: diff --git a/versioned_docs/version-v1.8/networking/hostnetworkconfig.md b/versioned_docs/version-v1.8/networking/hostnetworkconfig.md index d4566e4c1b..b33d2bea0e 100644 --- a/versioned_docs/version-v1.8/networking/hostnetworkconfig.md +++ b/versioned_docs/version-v1.8/networking/hostnetworkconfig.md @@ -319,17 +319,19 @@ Delete the config using the following command: :::caution -If a node has multiple host interfaces, do not connect them to the same VLAN or subnet. +If a node has multiple host interfaces, do not attach them to the same VLAN or subnet. This restriction applies to interfaces configured manually on the host and those configured through `HostNetwork` configurations. -VLAN interfaces under a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issue: -- **DHCP response misrouting**: When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This occurs because the DHCP `OFFER` packets can be delivered to `mgmt-br` instead of `mgmt-br.1`. +**DHCP Response Misrouting** -Configuring multiple interfaces in the same VLAN and subnet can result in ambiguous routing behavior. -- **Ambiguous kernel routing**: Linux typically installs a single connected route for a subnet. When multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended path. +VLAN interfaces used in a cluster network are derived from the same underlying bridge and consequently share the same MAC address. This shared MAC address can cause DHCP response misrouting. -For example, if a host network on cluster network `cn1` uses VLAN `2017` and receives subnet `192.168.0.0/24`, while another host network on cluster network `cn2` is also configured with VLAN `2017` and receives the same subnet 192.168.0.0/24, the kernel will install the connected route for 192.168.0.0/24 via only one interface (the latest configured). As a result, traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. +When multiple host interfaces from the same cluster network reside on the same VLAN, DHCP responses may be incorrectly associated with an existing interface instead of a newly created one. For example, if `mgmt-br` is connected to the native VLAN and has an active IP address, a DHCP client running on `mgmt-br.1` may fail to acquire a lease. This failure occurs because the DHCP `OFFER` packets are delivered to `mgmt-br` instead of `mgmt-br.1`. -This restriction applies to interfaces configured both manually on the host and through `HostNetwork` configurations. +**Ambiguous Routing Behavior** + +Additionally, configuring multiple interfaces in the same VLAN and subnet results in ambiguous routing. The Linux kernel typically installs a single connected route for a given subnet. If multiple interfaces are attached to the same VLAN and subnet, the kernel may associate the subnet route with only one of those interfaces, causing traffic to be forwarded through an unintended physical path. + +Example: Host networks on cluster networks `cn1` and `cn2` are both attached to VLAN `2017` and assigned the same subnet (`192.168.0.0/24`). Because both interfaces are in the same subnet, the Linux kernel will install the connected route for `192.168.0.0/24` via only one of those interfaces (typically the one configured last). Traffic destined for that subnet may be routed through the wrong interface, leading to unexpected issues. :::