CNV-47160: UDN support on public clouds

Author: Shikha Jhala

_topic_maps/_topic_map_rosa.yml

@@ -1997,6 +1997,8 @@ Topics:
     File: virt-networking-overview
   - Name: Connecting a VM to the default pod network
     File: virt-connecting-vm-to-default-pod-network
+  - Name: Connecting a VM to a primary user-defined network
+    File: virt-connecting-vm-to-primary-udn
   - Name: Exposing a VM by using a service
     File: virt-exposing-vm-with-service
 # Not supported in ROSA/OSD

modules/virt-about-services.adoc

@@ -21,3 +21,10 @@ ifndef::openshift-rosa,openshift-dedicated[]
 For on-premise clusters, you can configure a load-balancing service by deploying the MetalLB Operator.
 ====
 endif::openshift-rosa,openshift-dedicated[]
+
+ifdef::openshift-rosa,openshift-dedicated[]
+[NOTE]
+====
+For {product-rosa}, you must use `externalTrafficPolicy: Cluster` when configuring a load-balancing service, to minimize the network downtime during live migration.
+====
+endif::openshift-rosa,openshift-dedicated[]

modules/virt-networking-glossary.adoc

@@ -20,6 +20,10 @@ API resource that allows you to define custom resources, or an object defined by
 
 Network attachment definition (NAD):: A CRD introduced by the Multus project that allows you to attach pods, virtual machines, and virtual machine instances to one or more networks.
 
+UserDefinedNetwork (UDN):: A namespace-scoped CRD introduced by the user-defined network API that can be used to create a tenant network that isolates the tenant namespace from other namespaces.
+
+ClusterUserDefinedNetwork (CUDN):: A cluster-scoped CRD introduced by the user-defined network API that cluster administrators can use to create a shared network across multiple namespaces.
+
 ifndef::openshift-rosa,openshift-dedicated[]
 Node network configuration policy (NNCP):: A CRD introduced by the nmstate project, describing the requested network configuration on nodes.
 You update the node network configuration, including adding and removing interfaces, by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster.

virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc

@@ -10,7 +10,7 @@ You can connect a virtual machine (VM) to a user-defined network (UDN) on the VM
 
 {VirtProductName} supports the namespace-scoped `UserDefinedNetwork` and the cluster-scoped `ClusterUserDefinedNetwork` custom resource definitions (CRD). 
 
-Tenant owners can configure a primary `UserDefinedNetwork` CRD to create a network that isolates their namespace from other namespaces without requiring network policies. Cluster administrators can use the `ClusterUserDefinedNetwork` CRD to create a shared OVN network across multiple namespaces.
+Cluster administrators can configure a primary `UserDefinedNetwork` CRD to create a tenant network that isolates the tenant namespace from other namespaces without requiring network policies. Additionally, cluster administrators can use the `ClusterUserDefinedNetwork` CRD to create a shared OVN network across multiple namespaces.
 
 [NOTE]
 ====
@@ -65,7 +65,10 @@ include::modules/virt-creating-a-primary-cluster-udn.adoc[leveloffset=+2]
 
 include::modules/virt-attaching-vm-to-primary-udn.adoc[leveloffset=+1]
 
+//Excluding from ROSA because the Networking -> Multiple networks -> Primary networks section is not part of ROSA docs
+ifndef::openshift-rosa,openshift-dedicated[]
 [role="_additional-resources"]
 [id="additional-resources_{context}"]
 == Additional resources
-* xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-user-defined-networks[About user-defined networks]
+* xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-user-defined-networks[About user-defined networks]
+endif::openshift-rosa,openshift-dedicated[]

virt/vm_networking/virt-networking-overview.adoc

@@ -32,11 +32,16 @@ image:darkcircle-6.png[20,20] The machine network can be defined over a selected
 
 image:darkcircle-7.png[20,20] Secondary VM networks are typically bridged directly to a physical network, with or without VLAN encapsulation. It is also possible to create virtual overlay networks for secondary networks.
 
-[NOTE]
+[IMPORTANT]
 ====
 Connecting VMs directly to the underlay network is not supported on {product-rosa}.
 ====
 
+[NOTE]
+====
+Connecting VMs to user-defined networks with the `layer2` topology is recommended on public clouds.
+====
+
 image:darkcircle-8.png[20,20] Secondary VM networks can be defined on dedicated set of NICs, as shown in Figure 1, or they can use the machine network.
 
 include::modules/virt-networking-glossary.adoc[leveloffset=+1]
@@ -60,6 +65,15 @@ ifdef::openshift-rosa,openshift-dedicated[]
 You can expose a VM within the cluster or outside the cluster by creating a `Service` object.
 endif::openshift-rosa,openshift-dedicated[]
 
+[id="primary-udn-config"]
+== Configuring a primary user-defined network
+
+xref:../../virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc#virt-connecting-vm-to-primary-udn[Connecting a virtual machine to a primary user-defined network]::
+
+You can connect a virtual machine (VM) to a user-defined network (UDN) on the VM’s primary interface. The primary user-defined network replaces the default pod network to connect pods and VMs in selected namespaces. Cluster administrators can configure a primary `UserDefinedNetwork` CRD to create a tenant network that isolates the tenant namespace from other namespaces without requiring network policies. Additionally, cluster administrators can use the `ClusterUserDefinedNetwork` CRD to create a shared OVN `layer2` network across multiple namespaces.
++
+User-defined networks with the `layer2` overlay topology are useful for VM workloads, and a good alternative to secondary networks in environments where physical network access is limited, such as the public cloud. The `layer2` topology enables seamless migration of VMs without the need for Network Address Translation (NAT), and also provides persistent IP addresses that are preserved between reboots and during live migration.
+
 [id="secondary-network-config"]
 == Configuring VM secondary network interfaces