VPC NAT UI screenshots and Guest cluster using Overlay Networks by rrajendran17 · Pull Request #1085 · harvester/docs

rrajendran17 · 2026-07-15T19:40:25Z

Problem:

document for guest cluster using overlay networks

Solution:

document for guest cluster using overlay networks

Related Issue(s):

harvester/harvester#9682

Test plan:

Additional documentation or context

github-actions · 2026-07-15T19:46:35Z

Name	Link
🔨 Latest commit	`18c71c7`
😎 Deploy Preview	https://6a7a06c4a45316c1db1311db--harvester-preview.netlify.app

jillian-maroket

Review done for the new page. I'll go through the rest later.

jillian-maroket · 2026-07-17T08:18:22Z

+---
+sidebar_position: 11
+sidebar_label: Guest Cluster using Overlay Network
+title: "Guest Cluster using Overlay Network"


Suggested change

title: "Guest Cluster using Overlay Network"

title: "Guest Cluster Provisioning Using Underlay and Overlay Networks"

If this title is appropriate, we can shorten it for the sidebar.

jillian-maroket · 2026-07-17T08:18:40Z

+  <link rel="canonical" href="https://docs.harvesterhci.io/v1.9/rancher/guest-cluster-overlay-network"/>
+</head>
+
+## Provisioning Downstream Kubernetes Clusters on Harvester Using Rancher and Kube-OVN Networking


The subject of the page must be reflected in the title. This heading is not necessary. Please remove it.

jillian-maroket

@rrajendran17 I restructured some parts to make the procedures flow better.

jillian-maroket · 2026-07-23T11:09:23Z

+### SNAT for external connectivity from Overlay VMs

-##### Create EIP and SNAT resource
+#### Create EIP


Suggested change

### SNAT for external connectivity from Overlay VMs

##### Create EIP and SNAT resource

#### Create EIP

### SNAT Rules for Outbound Access (Overlay to External Networks)

#### Create an External IP

jillian-maroket

Approving now so we can merge and close the related issue. Note that I found some issues (capitalization, punctuation, markup, etc.) but I prefer to create my own PR for such cleanup work.

mergify · 2026-07-30T01:28:22Z

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

Queue this pull request

starbops

Thank you for the document update! I have a few nits below.

starbops · 2026-07-30T15:19:09Z

+
+For VMs provisioned as downstream cluster nodes, ensure external connectivity is available by enabling DHCP and configuring dns_server=8.8.8.8 and natOutgoing=true on the subnet. This allows the VMs to obtain a default route and perform DNS resolution.
+
+Since VMs attached to Kube-OVN overlay networks use private IP addresses, a route to the VM subnet must be configured on the rancher VM via the external IP used for SNAT/DNAT. This enables SSH access to the VM nodes from the Rancher UI.


This line is a bit confusing. Do we need a route to the VM subnet installed on the Rancher VM, or have DNAT/SNAT configured for the VM subnet? Or both?

A route is required for the private subnet with EIP (configured in the vpc nat gw) as nexthop.
I have rephrased the wording for better understanding in the latest commit.

starbops · 2026-08-04T10:08:14Z

+
+For VMs provisioned as downstream cluster nodes, ensure external connectivity is available by enabling DHCP and dns_server is set to a valid DNS server IP address (for example, `8.8.8.8`) and natOutgoing=true on the subnet. This allows the VMs to obtain a default route and perform DNS resolution.
+
+Since the guest cluster VM nodes over Kube-OVN overlay networks use private IP addresses, a route to the guest cluster VM node subnet must be configured on the Rancher VM with the Kube-OVN EIP (configured during the VPC NAT gateway EIP setup) as the next hop. This provides network reachability from the Rancher VM to the guest cluster VM nodes and enables SSH access through the Rancher UI.


I still have concerns about this paragraph. Are we sure that reverse connectivity from the external Rancher instance to the guest cluster running on an overlay network is required?

IIRC, Rancher Manager can manage clusters behind NAT. The cluster agent running in the guest cluster connects back to Rancher Manager and establishes long-lived connections that Rancher Manager then uses to communicate with the cluster.

I do not think we have any existing cases (before overlay networks) where the rancher instance has to ssh to a node IP which is private. The guest cluster VM Nodes created from a VM Vlan network will not have problem as they share the same subnet with the rancher VM.

In case of overlay networks, the node IP of the downstream VM Node will be for example 172.20.10.0/24 and to ssh to this node, rancher VM must have connectivity or know how to reach 172.20.10.0/24 which is not by default installed inside rancher VM. So by installing a route for private IP CIDR (node IP) via EIP, rancher VM sends the traffic for private IP to the GW (EIP of the NAT GW) and the GW will forward the traffic to corresponding VM acting as downstream node in 172.20.10.0/24 network.

This is not only for rancher instance but any external traffic communicates with the EIP (as only this is visible to the external networks) and VPC NAT GW relays the traffic to corresponding private IP based on configured DNAT rules.

By “SSH to this node,” do you mean that the external Rancher server must be able to access the node via SSH to provision or manage the downstream cluster?

According to Rancher’s documentation, its architecture is deliberately designed to avoid this requirement. The cluster agents running in the downstream cluster establish reverse tunnels to the external Rancher server, allowing Rancher to manage the cluster even when it is behind NAT.

As we discussed, updated it to make it more clearer for users that the ssh connectivity is required for debugging purposes.

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

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

rrajendran17 requested review from a team and jillian-maroket as code owners July 15, 2026 19:40

rrajendran17 requested a review from starbops July 15, 2026 19:40

github-actions Bot assigned rrajendran17 Jul 15, 2026

rrajendran17 changed the title ~~VPC NAT UI screenshots and Guest cluster using Overlay Networks~~ Draft:VPC NAT UI screenshots and Guest cluster using Overlay Networks Jul 15, 2026

rrajendran17 force-pushed the gc-overlaynetwork branch 5 times, most recently from 437ef52 to daa6ce9 Compare July 17, 2026 00:06

rrajendran17 changed the title ~~Draft:VPC NAT UI screenshots and Guest cluster using Overlay Networks~~ VPC NAT UI screenshots and Guest cluster using Overlay Networks Jul 17, 2026

jillian-maroket reviewed Jul 17, 2026

View reviewed changes

rrajendran17 mentioned this pull request Jul 17, 2026

[ENHANCEMENT] Support provisioning of guest clusters on Harvester VMs attached to overlay networks harvester/harvester#9682

Open

rrajendran17 force-pushed the gc-overlaynetwork branch 2 times, most recently from bd2e10c to 2edb74d Compare July 20, 2026 18:44

rrajendran17 requested a review from jillian-maroket July 20, 2026 19:08

jillian-maroket reviewed Jul 23, 2026

View reviewed changes

rrajendran17 force-pushed the gc-overlaynetwork branch 4 times, most recently from 6bfa449 to f07038f Compare July 24, 2026 18:03

rrajendran17 requested a review from jillian-maroket July 24, 2026 18:20

jillian-maroket previously approved these changes Jul 30, 2026

View reviewed changes

starbops reviewed Jul 30, 2026

View reviewed changes

rrajendran17 dismissed jillian-maroket’s stale review via 5104125 July 31, 2026 00:12

rrajendran17 force-pushed the gc-overlaynetwork branch from 65723a5 to 5104125 Compare July 31, 2026 00:12

rrajendran17 requested a review from starbops July 31, 2026 15:06

rrajendran17 requested a review from jillian-maroket July 31, 2026 15:06

starbops reviewed Aug 4, 2026

View reviewed changes

rrajendran17 requested a review from starbops August 4, 2026 17:56

rrajendran17 and others added 18 commits August 10, 2026 09:24

VPC NAT UI screenshots and Guest cluster using Overlay Networks

a1fb49e

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

Update docs/rancher/guest-cluster-overlay-network.md

f798b48

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/rancher/guest-cluster-overlay-network.md

bc27d0c

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/rancher/guest-cluster-overlay-network.md

4fbd0e1

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/rancher/guest-cluster-overlay-network.md

7afa206

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/rancher/guest-cluster-overlay-network.md

806db0a

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-pureunderlay.md

4c0d2d5

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-pureunderlay.md

d9c46f1

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

8616ee4

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

f72e739

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

7833445

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

ceddc21

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

5c14ba1

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

163fb4e

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

181ce34

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

f431988

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

400b7c7

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

Update docs/networking/kubeovn-vpcnatgateway.md

cb7900d

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

rrajendran17 force-pushed the gc-overlaynetwork branch 2 times, most recently from 6f0dfd5 to a0bb796 Compare August 10, 2026 16:55

Update docs/networking/kubeovn-vpcnatgateway.md

18c71c7

Co-authored-by: Jillian Maroket <67180770+jillian-maroket@users.noreply.github.com> Signed-off-by: Renuka Devi Rajendran <renuka.rajendran@suse.com>

rrajendran17 force-pushed the gc-overlaynetwork branch from a0bb796 to 18c71c7 Compare August 10, 2026 17:09

	title: "Guest Cluster using Overlay Network"
	title: "Guest Cluster Provisioning Using Underlay and Overlay Networks"


		For VMs provisioned as downstream cluster nodes, ensure external connectivity is available by enabling DHCP and configuring dns_server=8.8.8.8 and natOutgoing=true on the subnet. This allows the VMs to obtain a default route and perform DNS resolution.

		Since VMs attached to Kube-OVN overlay networks use private IP addresses, a route to the VM subnet must be configured on the rancher VM via the external IP used for SNAT/DNAT. This enables SSH access to the VM nodes from the Rancher UI.


		For VMs provisioned as downstream cluster nodes, ensure external connectivity is available by enabling DHCP and dns_server is set to a valid DNS server IP address (for example, `8.8.8.8`) and natOutgoing=true on the subnet. This allows the VMs to obtain a default route and perform DNS resolution.

		Since the guest cluster VM nodes over Kube-OVN overlay networks use private IP addresses, a route to the guest cluster VM node subnet must be configured on the Rancher VM with the Kube-OVN EIP (configured during the VPC NAT gateway EIP setup) as the next hop. This provides network reachability from the Rancher VM to the guest cluster VM nodes and enables SSH access through the Rancher UI.

Uh oh!

Conversation

rrajendran17 commented Jul 15, 2026

Problem:

Solution:

Related Issue(s):

Test plan:

Additional documentation or context

Uh oh!

github-actions Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jillian-maroket left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jillian-maroket left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jillian-maroket left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Jul 30, 2026

Uh oh!

starbops left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

starbops Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

github-actions Bot commented Jul 15, 2026 •

edited

Loading

jillian-maroket left a comment •

edited

Loading

rrajendran17 Aug 4, 2026 •

edited

Loading

starbops Aug 5, 2026 •

edited

Loading