Port content from community doc PRs (1064, 1082, 1103)

versions/v1.9/modules/en/pages/integrations/rancher/cloud-provider.adoc

@@ -1,5 +1,5 @@
 = Harvester Cloud Provider
-:revdate: 2026-07-06
+:revdate: 2026-08-18
 :page-revdate: {revdate}
 
 You can provision xref:integrations/rancher/node-driver/rke2-cluster.adoc[RKE2] clusters in Rancher using the built-in Harvester Node Driver. {harvester-product-name} provides <<#_load_balancer_support,load balancer>> and xref:integrations/rancher/csi-driver.adoc[storage passthrough] support to the guest Kubernetes cluster.
@@ -410,21 +410,96 @@ image::rancher/lb-svc.png[]
 
 {harvester-product-name}'s built-in load balancer offers both *DHCP* and *Pool* modes, and you can configure it by adding the annotation `cloudprovider.harvesterhci.io/ipam: $mode` to its corresponding service. Starting from Harvester Cloud Provider >= v0.2.0, it also introduces a unique *Share IP* mode. A service shares its load balancer IP with other services in this mode.
 
-* *DHCP:* A DHCP server is required. The {harvester-product-name} load balancer will request an IP address from the DHCP server.
+* *DHCP*: A DHCP server is required. The {harvester-product-name} load balancer will request an IP address from the DHCP server.
++
+Starting with *Rancher v2.15.1*, you can select a VM network when creating a `LoadBalancer` service using the UI. This enables explicit binding of the virtual IP to the correct network interface. If you do not select a VM network, the load balancer uses the default interface.
++
+In earlier Rancher versions (v2.12.x, v2.13.x, and v2.14.x), you can achieve the same result by adding the following annotations to the `Service` manifest:
++
+** `cloudprovider.harvesterhci.io/ipam: "dhcp"`
+** `cloudprovider.harvesterhci.io/network: "default/mgmt-vlan1"`
++
+image::rancher/guest-cluster-load-balancer-dhcp.png[Guest cluster load balancer (DHCP mode)]
 
-* *Pool:* You must first create an xref:networking/ip-pool.adoc[IP pool] using either the xref:networking/ip-pool.adoc#_creating_an_IP_pool[{harvester-product-name} UI] or the xref:networking/ip-pool.adoc#_creating_an_IP_pool_using_the_rancher_ui[{rancher-short-name} UI] (see xref:networking/ip-pool.adoc#_best_practices[Best practices] for information about the differences between the two methods). The {harvester-product-name} load balancer controller will allocate an IP for the load balancer service following xref:networking/ip-pool.adoc#_selection_policy[the IP pool selection policy].
+* *Pool*: A pre-configured xref:networking/ip-pool.adoc[IP pool] is required. The {harvester-product-name} load balancer controller allocates an IP for the load balancer service according to the xref:networking/ip-pool.adoc#_selection_policy[IP pool selection policy]. You can create IP pools using either the xref:networking/ip-pool.adoc#_creating_an_IP_pool[{harvester-product-name} UI] or the xref:networking/ip-pool.adoc#_creating_an_IP_pool_using_the_rancher_ui[{rancher-short-name} UI]. For more information, see xref:networking/ip-pool.adoc#_best_practices[Best practices].
++
+Starting with *Rancher v2.15.1*, you can select a VM network when creating a `LoadBalancer` service using the UI. This enables explicit binding of the load balancer to the correct network interface. If you do not select a VM network (specifically, the `cloudprovider.harvesterhci.io/network` is empty), the load balancer controller automatically determines the network to be used.
++
+On earlier Rancher versions (v2.12.x, v2.13.x, and v2.14.x), you can achieve the same result by adding the following annotations to the `Service` manifest:
++
+** `cloudprovider.harvesterhci.io/ipam: "ippool"`
+** `cloudprovider.harvesterhci.io/network: "default/mgmt-vlan1"`
++
+When a guest cluster uses multiple networks, or when multiple guest clusters with distinct networks share a single namespace, configuring the correct network parameters is critical. For information about how the system automatically determines the network, see xref:networking/ip-pool.adoc#_guest_cluster_load_balancer_network_resolution[Guest cluster load balancer network resolution].
++
+image::rancher/guest-cluster-load-balancer-pool.png[Guest cluster load balancer (Pool mode)]
 
-* *Share IP:* When creating a new load balancer service, you can re-utilize an existing load balancer service IP. The new service is referred to as a secondary service, while the currently chosen service is the primary one. To specify the primary service in the secondary service, you can add the annotation `cloudprovider.harvesterhci.io/primary-service: $primary-service-name`.  However, there are two known limitations:
- ** Services that share the same IP address can't use the same port.
- ** Secondary services cannot share their IP with additional services.
+* *Share IP*: When creating a new load balancer service (secondary service), you can reuse the IP address of an existing service (primary service). To specify the primary service, add the annotation `cloudprovider.harvesterhci.io/primary-service: $primary-service-name` to the secondary service.
++
+This mode has two known limitations:
++
+** Services sharing the same IP address cannot use identical ports.
+** Secondary services cannot share their IP with additional services.
 
 [NOTE]
 ====
-Modifying the `IPAM` mode isn't allowed. You must create a new service if you intend to change the `IPAM` mode.
+Modifying the IPAM mode of an existing service is not supported. To use a different IPAM mode, create a new load balancer service.
 
 See xref:troubleshooting/rancher.adoc#_guest_cluster_load_balancer_ip_is_not_reachable[Guest cluster load balancer IP is not reachable].
 ====
 
+[#_asymmetric_topology]
+=== Asymmetric network topology
+
+The network dropdown list on the UI displays only networks assigned to the _exact same interface position across all cluster nodes_.
+
+Example:
+
+|===
+| Network-Interface Mapping | UI Behavior | Node A | Node B | Displayed Networks
+
+| Identical mapping across all nodes
+| All networks are displayed
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-101`
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-101`
+| `mgmt` and `net-101`
+
+| Network in different interface positions across nodes
+| Network is hidden
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-101`
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-102`<br/>`enp3s0` → `net-101`
+| `mgmt`
+
+| Network absent on some nodes
+| Network is hidden
+| `enp1s0` → `mgmt`
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-101`
+| `mgmt`
+
+| Swapped interface mapping order
+| Only matching networks are displayed
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-101`<br/>`enp3s0` → `net-102`
+| `enp1s0` → `mgmt`<br/>`enp2s0` → `net-102`<br/>`enp3s0` → `net-101`
+| `mgmt`
+|===
+
+[TIP]
+====
+If VM network interfaces are attached in different orders across nodes, reconfigure the network interface order in the machine pool settings to allow Rancher and RKE2 to reprovision the guest cluster virtual machines.
+====
+
+=== Limitations
+
+* *Default load balancer provider*: `kube-vip` is selected by default on the UI. If you disable `kube-vip` and use an alternative provider, refer to that provider's documentation for configuration instructions.
+
+* *Pre-condition for secondary network load balancing*: The secondary network interface of each guest cluster node must have a valid IP address and route. Otherwise, the load balancer cannot route traffic. Verifying this interface configuration should be the first step when troubleshooting issues related to secondary network load balancers.
+
+* *Load balancer network changes*: Delete and recreate the load balancer service if you require changes to the load balancer network. Modifying the network annotation on an existing service may cause unexpected behavior and is not supported.
+
+* *Incorrect network annotation*: The load balancer may fail to obtain an IP address or become unreachable if you directly configure the `cloudprovider.harvesterhci.io/network` annotation and specify a network that is either invalid or exhibits an <<#_asymmetric_topology,asymmetric network topology>>. Because webhook validation is not performed on this annotation, select the target network on the UI instead.
+
+* *Secondary network load balancer traffic isolation*: Incoming traffic arrives on the secondary network interface and undergoes NAT to the pod network. Consequently, only workloads listening on the pod network can receive load balancer traffic. Workloads configured to listen exclusively on the secondary network interface cannot. Full traffic isolation is currently unsupported.
+
 === Health checks
 
 Beginning with Harvester Cloud Provider v0.2.0, additional health checks of the `LoadBalancer` service within the guest Kubernetes cluster are no longer necessary. Instead, you can configure https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-tcp-liveness-probe[liveness] and https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes[readiness] probes for your workloads. Consequently, any unavailable pods will be automatically removed from the load balancer endpoints to achieve the same desired outcome.

versions/v1.9/modules/en/pages/networking/ip-pool.adoc

@@ -1,5 +1,5 @@
 = IP Pool
-:revdate: 2026-06-16
+:revdate: 2026-08-18
 :page-revdate: {revdate}
 
 IP Pool is a built-in IP address management (IPAM) solution exclusively available to {harvester-product-name} load balancers (LBs).
@@ -64,6 +64,34 @@ Network matching is not enforced. This means that a global IP pool could inadver
 For information about risk mitigation and resource allocation, see <<Best practices>>.
 ====
 
+== Guest cluster load balancer network resolution
+
+When a user or application creates a LoadBalancer service inside a guest cluster, the Harvester Cloud Provider sends a creation request to the {harvester-product-name} cluster's API server.
+
+Before persisting the object, the API server invokes the load balancer mutating webhook to automatically resolve and apply the correct network annotation. After the object is saved, the backend controller asynchronously manages IP pool matching and allocation.
+
+=== Network resolution workflow ({harvester-product-name} v1.8 and earlier)
+
+During the automatic resolution phase, the webhook performs a basic network lookup:
+
+* Fetches all VMIs with the label `harvesterhci.io/creator:docker-machine-driver-harvester` from the load balancer's namespace.
+* Filters for VMIs using `<cluster-name>` as a prefix.
+* Selects the first `multus-network` name.
+
+=== Network resolution workflow ({harvester-product-name} v1.9.0 and later)
+
+Before handing off the resource to the backend controller, the webhook evaluates the following conditions in sequential order:
+
+. *Existing load balancer annotation*: The webhook uses the value of the annotation `loadbalancer.harvesterhci.io/network` if present and non-empty.
+. *Management network annotation*: The webhook uses the value of the annotation `cloudprovider.harvesterhci.io/managementNetwork` if present and non-empty.
+. *Guest cluster label lookup*: The webhook fetches all VMIs with the label `guestcluster.harvesterhci.io/name: <cluster-name>` from the load balancer's namespace and selects the first `multus-network` name.
+. *Legacy driver label fallback*: The webhook fetches all VMIs with the label `harvesterhci.io/creator:docker-machine-driver-harvester` from the load balancer's namespace, filters for VMIs using `<cluster-name>` as a prefix, and selects the first `multus-network` name.
++
+[NOTE]
+====
+This final step serves as a fallback path to maintain backward compatibility with guest clusters deployed using {harvester-product-name} v1.8 or earlier.
+====
+
 === Examples
 
 * *Example 1:* You wish to set up an IP pool within the range `192.168.100.0/24` for the `default` namespace. In this scenario, all load balancers within the `default` namespace will receive an IP address from this designated IP pool: