HostNetwork configuration and underlay selection user guide by rrajendran17 · Pull Request #999 · harvester/docs

rrajendran17 · 2026-03-27T08:51:47Z

Problem:

User guide for hostnetworkconfig and underlay selection for overlay networks

Solution:

User guide for hostnetworkconfig and underlay selection for overlay networks

Related Issue(s):

harvester/harvester#8101
harvester/harvester#7834

Copilot

Pull request overview

Adds a new networking documentation page describing how to configure HostNetworkConfig for VLAN sub-interfaces (DHCP/static, node selectors, mgmt network) and how to select a non-management underlay for Kube-OVN overlay VM traffic.

Changes:

New user guide for creating HostNetworkConfig resources with DHCP/static addressing and optional node targeting.
Documentation for setting an overlay underlay via underlay: true, including behavior/limitations and verification steps.
Adds a troubleshooting section and operational behavior notes (reboots, node additions, deletes/updates).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-27T08:55:36Z

docs/networking/hostnetworkconfig.md

+    a node
+                                        Node does not have an uplink
+                                        or label selector mismatch
+                                                                                          Check VlanConfig node.verify selector;


The resolution text Check VlanConfig node.verify selector; is unclear and appears to contain a typo ("node.verify"). Please update it to reference the actual VlanConfig node selector field and what users should verify (e.g., that the selector matches the node labels).

Suggested change

Check VlanConfig node.verify selector;

Verify that the VlanConfig spec.nodeSelector matches the labels on the target nodes

docs/networking/hostnetworkconfig.md

Copilot · 2026-03-27T08:55:37Z

docs/networking/hostnetworkconfig.md

+  ### Troubleshooting
+
+  Symptom                              Likely Cause                                        Resolution
+
+  1.Webhook rejects the resource       VLAN ID is 0, or missing node IPs in static mode   Verify cluster network 
+                                                                                          status; use VLAN ID ≥ 1; provide IPs for all nodes
+
+  2.Sub-interface not created on
+    a node
+                                        Node does not have an uplink
+                                        or label selector mismatch
+                                                                                          Check VlanConfig node.verify selector;
+
+  3.DHCP lease not obtained            No DHCP server reachable on the VLAN               Confirm DHCP server
+                                                                                          is reachable on the configured VLAN from the node
+
+  4.underlay: true rejected          Another HostNetworkConfig is already set as the
+                                     underlay, or coverage is not cluster-wide
+                                                                                          Remove the underlay flag from the existing config first; ensure the new config covers all nodes
+
+  5.VM traffic not using new underlay     KubeOVN annotation not yet propagated           Check
+                                                                                          ovn.kubernetes.io/     tunnel_interface annotation on each node; allow time for KubeOVN to reconcile
+


The "Troubleshooting" section is not valid Markdown table/list formatting (spacing will be collapsed, and entries like 1.Webhook won't render as an ordered list). Consider rewriting this as a proper Markdown table (| Symptom | Likely cause | Resolution |) or a structured list so it renders predictably.

Suggested change

### Troubleshooting

Symptom Likely Cause Resolution

1.Webhook rejects the resource VLAN ID is 0, or missing node IPs in static mode Verify cluster network

status; use VLAN ID ≥ 1; provide IPs for all nodes

2.Sub-interface not created on

a node

Node does not have an uplink

or label selector mismatch

Check VlanConfig node.verify selector;

3.DHCP lease not obtained No DHCP server reachable on the VLAN Confirm DHCP server

is reachable on the configured VLAN from the node

4.underlay: true rejected Another HostNetworkConfig is already set as the

underlay, or coverage is not cluster-wide

Remove the underlay flag from the existing config first; ensure the new config covers all nodes

5.VM traffic not using new underlay KubeOVN annotation not yet propagated Check

ovn.kubernetes.io/ tunnel_interface annotation on each node; allow time for KubeOVN to reconcile

### Troubleshooting

| Symptom | Likely cause | Resolution |

| ----------------------------------- | -------------------------------------------------- | ---------- |

| Webhook rejects the resource | VLAN ID is 0, or missing node IPs in static mode | Verify cluster network status; use VLAN ID ≥ 1; provide IPs for all nodes |

| Sub-interface not created on a node | Node does not have an uplink, or label selector mismatch | Check VlanConfig node selector; ensure the node has the required uplink configuration |

| DHCP lease not obtained | No DHCP server reachable on the VLAN | Confirm DHCP server is reachable on the configured VLAN from the node |

| `underlay: true` rejected | Another HostNetworkConfig is already set as the underlay, or coverage is not cluster-wide | Remove the underlay flag from the existing config first; ensure the new config covers all nodes |

| VM traffic not using new underlay | KubeOVN annotation not yet propagated | Check `ovn.kubernetes.io/tunnel_interface` annotation on each node; allow time for KubeOVN to reconcile |

Copilot · 2026-03-27T08:55:37Z

docs/networking/hostnetworkconfig.md

+                                                                                          Remove the underlay flag from the existing config first; ensure the new config covers all nodes
+
+  5.VM traffic not using new underlay     KubeOVN annotation not yet propagated           Check
+                                                                                          ovn.kubernetes.io/     tunnel_interface annotation on each node; allow time for KubeOVN to reconcile


This troubleshooting item breaks the annotation name across whitespace (ovn.kubernetes.io/ tunnel_interface), which can confuse users copying it. Keep it as the exact annotation key ovn.kubernetes.io/tunnel_interface on one line.

Suggested change

ovn.kubernetes.io/ tunnel_interface annotation on each node; allow time for KubeOVN to reconcile

ovn.kubernetes.io/tunnel_interface annotation on each node; allow time for KubeOVN to reconcile

docs/networking/hostnetworkconfig.md

Copilot · 2026-03-27T08:55:38Z

docs/networking/hostnetworkconfig.md

+```
+apiVersion: network.harvesterhci.io/v1beta1
+kind: HostNetworkConfig
+metadata:
+  name: br1-vlan2012-dhcp
+spec:
+  clusterNetwork: br-1
+  vlanID: 2012
+  mode: dhcp
+```


The YAML examples are fenced with plain triple-backticks, but networking docs elsewhere consistently use language-tagged fences (e.g., ```yaml) for manifests. Adding the yaml info string improves readability/syntax highlighting and keeps this page consistent with the rest of the section.

Copilot · 2026-03-27T08:55:38Z

docs/networking/hostnetworkconfig.md

+Harvester supports the creation of VLAN sub-interfaces on cluster networks and the assignment of IPv4 addresses to those interfaces. This enables Layer 3 connectivity from Harvester nodes to external networks — for dedicated storage, isolated application traffic, or integration with existing routing infrastructure.
+A related capability allows users to designate one of these VLAN interfaces as the underlay for KubeOVN overlay networks used by virtual machines, separating VM inter-node traffic from management traffic.
+


The text uses both "KubeOVN" and "Kube-OVN" on the same page (frontmatter keywords use "Kube-OVN"). Please standardize on the project name used across the docs ("Kube-OVN") so search/keywords and references are consistent.

github-actions · 2026-03-30T02:25:37Z

Name	Link
🔨 Latest commit	`6d6e123`
😎 Deploy Preview	https://69c9e2d5f9e81cd90b339414--harvester-preview.netlify.app

Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

akashraj4261 · 2026-03-30T08:08:28Z

docs/networking/hostnetworkconfig.md

+### Prerequisites
+Before creating a HostNetworkConfig, ensure the following:
+
+The target cluster network (e.g., br-1, mgmt) is created and in Ready state.


Suggested change

The target cluster network (e.g., br-1, mgmt) is created and in Ready state.

The target cluster network (for example, br-1, mgmt) is created and in Ready state.

Copilot AI review requested due to automatic review settings March 27, 2026 08:51

github-actions bot requested review from akashraj4261, dariavladykina and jillian-maroket March 27, 2026 08:51

github-actions bot assigned rrajendran17 Mar 27, 2026

Copilot started reviewing on behalf of rrajendran17 March 27, 2026 08:52 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

rrajendran17 force-pushed the hostnetworkconfig-userdoc branch 2 times, most recently from beb642b to 48a8bc4 Compare March 30, 2026 02:19

HostNetwork configuration user guide

7b3aeba

Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

rrajendran17 force-pushed the hostnetworkconfig-userdoc branch from 95406d2 to 7b3aeba Compare March 30, 2026 02:37

Merge branch 'main' into hostnetworkconfig-userdoc

6d6e123

rrajendran17 requested a review from a team March 30, 2026 02:46

akashraj4261 reviewed Mar 30, 2026

View reviewed changes

akashraj4261 approved these changes Mar 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HostNetwork configuration and underlay selection user guide#999

HostNetwork configuration and underlay selection user guide#999
rrajendran17 wants to merge 2 commits intoharvester:mainfrom
rrajendran17:hostnetworkconfig-userdoc

rrajendran17 commented Mar 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

Copilot AI Mar 27, 2026

Uh oh!

github-actions bot commented Mar 30, 2026 •

edited

Loading

Uh oh!

akashraj4261 Mar 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	Check VlanConfig node.verify selector;
	Verify that the VlanConfig spec.nodeSelector matches the labels on the target nodes

	ovn.kubernetes.io/ tunnel_interface annotation on each node; allow time for KubeOVN to reconcile
	ovn.kubernetes.io/tunnel_interface annotation on each node; allow time for KubeOVN to reconcile

		Harvester supports the creation of VLAN sub-interfaces on cluster networks and the assignment of IPv4 addresses to those interfaces. This enables Layer 3 connectivity from Harvester nodes to external networks — for dedicated storage, isolated application traffic, or integration with existing routing infrastructure.
		A related capability allows users to designate one of these VLAN interfaces as the underlay for KubeOVN overlay networks used by virtual machines, separating VM inter-node traffic from management traffic.

	The target cluster network (e.g., br-1, mgmt) is created and in Ready state.
	The target cluster network (for example, br-1, mgmt) is created and in Ready state.

Conversation

rrajendran17 commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem:

Solution:

Related Issue(s):

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

akashraj4261 Mar 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rrajendran17 commented Mar 27, 2026 •

edited

Loading

github-actions bot commented Mar 30, 2026 •

edited

Loading