Add note for host network config behaviour

[rrajendran17]

Problem:

The issue occurs when the host is attached multiple times to the same Layer 2 network. In the VLAN 1 case, mgmt-br already represents the native/untagged VLAN 1 network, and creating mgmt-br.1 adds a second host interface to the same broadcast domain. DHCP DISCOVER packets are transmitted successfully, but the DHCP OFFER is associated with the existing interface (mgmt-br) rather than the VLAN subinterface (mgmt-br.1), causing the DHCP client to never complete lease acquisition.

More generally, a node should not have multiple host interfaces connected to the same VLAN/subnet

Solution:

document the behaviour so users know what to configure

Related Issue(s):

harvester/harvester#10802

Test plan:

Additional documentation or context

[github-actions]

Name	Link
🔨 Latest commit	f727a64
😎 Deploy Preview	https://6a57aaf24eda9012bf185379--harvester-preview.netlify.app

[jillian-maroket]

Review done

[jillian-maroket]

Suggested change

	:::note
	A node must not have multiple host interfaces connected to the same VLAN/subnet. Within the same cluster network, VLAN interfaces are derived from the same bridge and therefore use the same MAC address. When multiple host interfaces are attached to the same VLAN, DHCP responses may be associated with the existing interface instead of the newly created one. For example, if mgmt-br is already connected to the native VLAN and has an IP address, a DHCP client running on mgmt-br.1 may not successfully acquire a lease because DHCP OFFER packets can be delivered to mgmt-br rather than mgmt-br.1.
	In addition to DHCP issues, configuring multiple host interfaces in the same VLAN/subnet on a node can result in ambiguous routing behavior because the kernel installs routes for the subnet through a single interface, which may cause traffic to be routed through an unintended interface.
	The above applies to both host interfaces configured manually and through hostnetwork configurations.
	:::caution
	If a node has multiple host interfaces, do not connect them to the same VLAN or subnet.
	VLAN interfaces in a cluster network are derived from the same bridge and therefore use the same MAC address. This can cause the following issues:
	- **DHCP response misrouting**: When multiple host interfaces 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`.
	- **Ambiguous kernel routing**: Configuring multiple interfaces in the same VLAN or subnet can result in ambiguous routing behavior. The Linux kernel installs subnet routes through a single interface, which may force traffic through an unintended path.
	This restriction applies to interfaces configured both manually on the host and through `HostNetwork` configurations.

[Yu-Jack]

Could we do like - if user had created the host network config, then attached multiple same VLAN, we would show the warning in host network config resource?

[rrajendran17]

Thanks @Yu-Jack , webhook was my initial decision, but the problem is we need to get the existing interfaces on harvester host to compare the vlan with the host network config vlan id.
The webhook pod runs as deployment pod and host network is not enabled, so it will not be able to get the host interfaces. Even if we enable host network, since its a deployment pod it cannot get interfaces from all nodes.
So this will not be an option in webhook to validate.

Yeah other possibility is showing this as warning/error message in status from controller, but I thought these are network configuration errors so its better to educate the users through docs instead of handling those in controllers.
we will come across other misconfiguration from users in future also.

[Yu-Jack]

Yeah other possibility is showing this as warning/error message in status from controller, but I thought these are network configuration errors so its better to educate the users through docs instead of handling those in controllers.
we will come across other misconfiguration from users in future also.

Actually it's a good idea to show the message in status via controller.

Here is my thought.

We provide two entries to users:

1. the message in status
2. this document

First option is for users that are encountering the issue.

Second option is for users that are going to do this if they remember to check the document firstly.

However, since we have the deadline, it's not really necessary, just a suggestion.

[jillian-maroket]

The note is now very long because of the new text. However, I first need to evaluate the adjacent topics before creating a dedicated section for this. I still suggested using headings to break up the concepts even if we have to bold them for now (a crude solution).

[jillian-maroket]

Please remove this line. I moved the sentence to paragraph 1.

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request