doc(networking): add detailed explanation regarding route connectivity

Signed-off-by: Zespre Chang <[email protected]>

Author: starbops

docs/networking/harvester-network.md

@@ -80,7 +80,7 @@ The [Harvester network-controller](https://github.com/harvester/harvester-networ
     ![](/img/v1.2/networking/create-network-manual.png)
 
     :::info important
-    Harvester uses the information to verify that all nodes can access the VM network you are creating. If that is the case, the *Network connectivity* column on the **VM Networks** screen indicates that the network is active. Otherwise, the screen indicates that an error has occurred.
+    Harvester uses the information to verify that all nodes can access the VM network you are creating. If that is the case, the *Network connectivity* column on the **VM Networks** screen indicates that the network is active. Otherwise, the screen indicates that an error has occurred. Please check [the Route Connectivity section](#about-route-connectivity) for more details.
     :::
 
 ### Create a VM with VLAN Network
@@ -106,3 +106,32 @@ To create a new untagged network, go to the **Networks > VM Networks** page and
 Starting from Harvester v1.1.2, Harvester supports updating and deleting VM networks. Make sure to stop all affected VMs before updating or deleting VM networks.
 
 :::
+
+## About Route Connectivity
+
+![](/img/v1.3/networking/route-connectivity.png)
+
+There are four possible cases for the **Route Connectivity** for each VM Network:
+
+- `Active`, meaning the connectivity between the VM Network and Harvester hosts via the configured gateway is confirmed.
+- `Dhcp failed`, meaning Harvester cannot get the route information via DHCP, therefore it cannot confirm the connectivity between the VM Network and Harvester hosts. Please ensure the DHCP server is configured appropriately and is L2-reachable (or routable if a DHCP relay server is provided in the target network). Otherwise, please provide the gateway IP address directly during the VM Network creation.
+- `Ping failed`, meaning Harvester is unable to send ICMP Echo Request packets. This rarely happens.
+- `Inactive`, meaning such a VM Network is not reachable (or reachable but packet loss is greater than 20%) from Harvester hosts. Please ensure the gateway is configured appropriately and is reachable via the management network where the Harvester nodes live.
+
+:::info important
+
+For the [VM load balancer feature](./loadbalancer#vm-load-balancer) to work, the VM network must be `Active` in terms of route connectivity.
+
+:::
+
+Behind the scenes, the Harvester network controller checks the connectivity of each VM Network. Connectivity means whether the target VM Network is reachable (via router(s) if necessary) from the Harvester node. The check is essential because it indicates that such a VM Network is suitable for running workloads that require connections to the Harvester node, especially the control plane. For instance, the Harvester cloud provider that is running in the guest cluster needs to access the underlying Harvester/Kubernetes APIs to be able to calculate the node topology and provide the load balancer feature.
+
+To check the connectivity, the gateway IP address is of interest to the Harvester network controller. Such information could be absent during  VM Network creation. However, it's still possible to get it if a DHCP server is running on the target VM Network and configured with the gateway information. If the user actively provides the gateway information during network creation, the network controller happily accepts it. Otherwise, the network controller will create a helper job on the target network that acts as a DHCP client to get the gateway information. With the gateway IP address in mind, the network controller then sends ICMP Echo Request packets from the management network to the gateway and waits for responses.
+
+To wrap up, the **Route Connectivity** for VM Networks is an important indicator representing the connectivity between the VM Network and the management network where the Harvester nodes live.
+
+:::note
+
+If a VM Network's route connectivity is `Dhcp failed`, `Ping failed`, or `Inactive`, it doesn't mean the network is entirely unusable. It depends on what you're going to do with the network. Suppose you only want to run some workloads that should be completely isolated from any other network, including the management network where the Harvester nodes live. In that case, the VM Network is suitable for the job. Whether or not the VM Network has Internet connectivity is not the concern of the Harvester network controller.
+
+:::