openshift · sjhala-ccs · Jun 13, 2025 · May 27, 2025
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -4795,6 +4795,8 @@ Topics:
     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: Connecting a VM to a secondary localnet user-defined network
+    File: virt-connecting-vm-to-secondary-udn
   - Name: Exposing a VM by using a service
     File: virt-exposing-vm-with-service
   - Name: Accessing a VM by using its internal FQDN
@@ -4805,7 +4807,7 @@ Topics:
     File: virt-connecting-vm-to-sriov
   - Name: Using DPDK with SR-IOV
     File: virt-using-dpdk-with-sriov
-  - Name: Connecting a VM to an OVN-Kubernetes secondary network
+  - Name: Connecting a VM to an OVN-Kubernetes layer 2 secondary network
     File: virt-connecting-vm-to-ovn-secondary-network
   - Name: Hot plugging secondary network interfaces
     File: virt-hot-plugging-network-interfaces

diff --git a/modules/virt-attaching-vm-to-secondary-udn.adoc b/modules/virt-attaching-vm-to-secondary-udn.adoc
@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * virt/vm_networking/virt-connecting-vm-to-secondary-udn.adoc
+
+:_mod-docs-content-type: PROCEDURE                                
+[id="virt-attaching-vm-to-secondary-udn_{context}"]                                  
+= Attaching a virtual machine to secondary user-defined networks by using the CLI
+
+You can connect a virtual machine (VM) to multiple secondary cluster-scoped user-defined networks (CUDNs) by configuring the interface binding.
+
+.Prerequisites
+* You have installed the {oc-first}.
+
+.Procedure
+. Edit the `VirtualMachine` manifest to add the CUDN interface details, as in the following example:
++
+.Example `VirtualMachine` manifest
+[source,yaml]
+----
+apiVersion: kubevirt.io/v1
+kind: VirtualMachine
+metadata:
+  name: example-vm
+  namespace: my-namespace # <1>
+spec:
+  template:
+    spec:
+      domain:
+        devices:
+          interfaces:
+            - name: secondary_localnet # <2>
+              bridge: {}
+        machine:
+          type: ""
+        resources:
+          requests:
+            memory: 2048M               
+      networks:
+      - name: secondary_localnet # <3>
+        multus:
+          networkName: <localnet_cudn_name> # <4>
+# ...
+----
+<1> The namespace in which the VM is located. This value must match a namespace that is associated with the secondary CUDN.
+<2> The name of the secondary user-defined network interface.
+<3> The name of the network. This must match the value of the `spec.template.spec.domain.devices.interfaces.name` field.
+<4> The name of the localnet `ClusterUserDefinedNetwork` object that you previously created.
+
+. Apply the `VirtualMachine` manifest by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
++
+where:
+
+<filename>:: Specifies the name of your `VirtualMachine` manifest YAML file.
diff --git a/modules/virt-creating-a-primary-cluster-udn.adoc b/modules/virt-creating-a-primary-cluster-udn.adoc
@@ -41,7 +41,7 @@ spec:
 <3> Specifies the type of selector. In this example, the `matchExpressions` selector selects objects that have the label `kubernetes.io/metadata.name` with the value `red-namespace` or `blue-namespace`.
 <4> Specifies the type of operator. Possible values are `In`, `NotIn`, and `Exists`.
 <5> Specifies the topological configuration of the network. The required value is `Layer2`. A `Layer2` topology creates a logical switch that is shared by all nodes.
-<6> Specifies if the UDN is primary or secondary. {VirtProductName} only supports the `Primary` role. This means that the UDN acts as the primary network for the VM and all default traffic passes through this network.
+<6> Specifies whether the UDN is primary or secondary. The `Primary` role means that the UDN acts as the primary network for the VM and all default traffic passes through this network.
 
 . Apply the `ClusterUserDefinedNetwork` manifest by running the following command:
 +

diff --git a/modules/virt-creating-a-primary-udn.adoc b/modules/virt-creating-a-primary-udn.adoc
@@ -36,7 +36,7 @@ spec:
 <1> Specifies the name of the `UserDefinedNetwork` custom resource. 
 <2> Specifies the namespace in which the VM is located. The namespace must have the `k8s.ovn.org/primary-user-defined-network` label. The namespace must not be `default`, an `openshift-*` namespace, or match any global namespaces that are defined by the Cluster Network Operator (CNO).
 <3> Specifies the topological configuration of the network. The required value is `Layer2`. A `Layer2` topology creates a logical switch that is shared by all nodes.
-<4> Specifies if the UDN is primary or secondary. {VirtProductName} only supports the `Primary` role. This means that the UDN acts as the primary network for the VM and all default traffic passes through this network.
+<4> Specifies whether the UDN is primary or secondary. The `Primary` role means that the UDN acts as the primary network for the VM and all default traffic passes through this network.
 <5> Specifies that virtual workloads have consistent IP addresses across reboots and migration. The `spec.layer2.subnets` field is required when `ipam.lifecycle: Persistent` is specified.
 
 . Apply the `UserDefinedNetwork` manifest by running the following command:

diff --git a/modules/virt-creating-secondary-localnet-udn.adoc b/modules/virt-creating-secondary-localnet-udn.adoc
@@ -0,0 +1,102 @@
+// Module included in the following assemblies:
+//
+// * virt/vm_networking/virt-connecting-vm-to-secondary-udn.adoc        
+
+:_mod-docs-content-type: PROCEDURE                                  
+[id="virt-creating-secondary-localnet-udn_{context}"]                                  
+= Creating a user-defined-network for localnet topology by using the CLI
+
+You can create a secondary cluster-scoped user-defined-network (CUDN) for the localnet network topology by using the CLI.
+
+.Prerequisites
+* You are logged in to the cluster as a user with `cluster-admin` privileges.
+* You have installed the {oc-first}.
+* You installed the Kubernetes NMState Operator.
+
+.Procedure
+. Create a `NodeNetworkConfigurationPolicy` object to map the OVN-Kubernetes secondary network to an Open vSwitch (OVS) bridge:
++
+.Example `NodeNetworkConfigurationPolicy` manifest
+[source,yaml]
+----
+apiVersion: nmstate.io/v1
+kind: NodeNetworkConfigurationPolicy
+metadata:
+  name: mapping # <1>
+spec:
+  nodeSelector:
+    node-role.kubernetes.io/worker: '' # <2>
+  desiredState:
+    ovn:
+      bridge-mappings:
+      - localnet: tenantblue # <3>
+        bridge: br-ex # <4>
+        state: present # <5>
+----
+<1> The name of the configuration object.
+<2> Specifies the nodes to which the node network configuration policy is applied. The recommended node selector value is `node-role.kubernetes.io/worker: ''`.
+<3> The name of the additional network from which traffic is forwarded to the OVS bridge. This attribute must match the value of the `spec.network.localnet.physicalNetworkName` field of the `ClusterUserDefinedNetwork` object that defines the OVN-Kubernetes additional network. This example uses the name `tenantblue`.
+<4> The name of the OVS bridge on the node. This value is required if the `state` attribute is `present` or not specified.
+<5> The state of the mapping. Must be either `present` to add the mapping or `absent` to remove the mapping. The default value is `present`.
++
+[IMPORTANT]
+====
+{VirtProductName} does not support Linux bridge bonding modes 0, 5, and 6. For more information, see link:https://access.redhat.com/solutions/67546[Which bonding modes work when used with a bridge that virtual machine guests or containers connect to?].
+====
+
+. Apply the `NodeNetworkConfigurationPolicy` manifest by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
++
+where:
+
+<filename>:: Specifies the name of your `NodeNetworkConfigurationPolicy` manifest YAML file.
+
+. Create a `ClusterUserDefinedNetwork` object to create a localnet secondary network:
++
+.Example `ClusterUserDefinedNetwork` manifest
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: ClusterUserDefinedNetwork
+metadata:
+  name: cudn-localnet # <1>
+spec:
+  namespaceSelector: # <2>
+    matchExpressions: # <3>
+    - key: kubernetes.io/metadata.name
+      operator: In # <4>
+      values: ["red", "blue"]
+  network:
+    topology: Localnet # <5>
+    localnet:
+        role: Secondary # <6>
+        physicalNetworkName: tenantblue # <7>
+        ipam:
+          mode: Disabled # <8>
+# ...
+----
+<1> The name of the `ClusterUserDefinedNetwork` custom resource.
+<2> The set of namespaces that the cluster UDN applies to. The namespace selector must not point to the following values: `default`; an `openshift-*` namespace; or any global namespaces that are defined by the Cluster Network Operator (CNO).
+<3> The type of selector. In this example, the `matchExpressions` selector selects objects that have the label `kubernetes.io/metadata.name` with the value `red` or `blue`.
+<4> The type of operator. Possible values are `In`, `NotIn`, and `Exists`.
+<5> The topological configuration of the network. A `Localnet` topology connects the logical network to the physical underlay.
+<6> Specifies whether the UDN is primary or secondary. The required value is `Secondary` for `topology: Localnet`.
+<7> The name of the OVN-Kubernetes bridge mapping that is configured on the node. This value must match the `spec.desiredState.ovn.bridge-mappings.localnet` field in the `NodeNetworkConfigurationPolicy` manifest that you previously created. This ensures that you are bridging to the intended segment of your physical network.
+<8> Specifies whether IP address management (IPAM) is enabled or disabled. The required value is `Disabled`. {VirtProductName} does not support configuring IPAM for virtual machines.
+
+. Apply the `ClusterUserDefinedNetwork` manifest by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f <filename>.yaml
+----
++
+where:
+
+<filename>:: Specifies the name of your `ClusterUserDefinedNetwork` manifest YAML file.
+
+
diff --git a/modules/virt-creating-secondary-udn-namespace.adoc b/modules/virt-creating-secondary-udn-namespace.adoc
@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * virt/vm_networking/virt-connecting-vm-to-secondary-udn.adoc              
+
+:_mod-docs-content-type: PROCEDURE                                    
+[id="virt-creating-secondary-udn-namespace_{context}"]                                   
+= Creating a namespace for secondary user-defined networks by using the CLI
+
+You can create a namespace to be used with an existing secondary cluster-scoped user-defined network (CUDN) by using the CLI.
+
+.Prerequisites
+* You are logged in to the cluster as a user with `cluster-admin` permissions.
+* You have installed the {oc-first}.
+
+
+.Procedure
+. Create a `Namespace` object similar to the following example:
++
+.Example `Namespace` manifest
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: cudn_namespace
+# ...
+----
+
+. Apply the `Namespace` manifest by running the following command:
++
+[source, terminal]
+----
+oc apply -f <filename>.yaml
+----
++
+where:
+
+<filename>:: Specifies the name of your `Namespace` manifest YAML file.
diff --git a/virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc b/virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
 [id="virt-connecting-vm-to-ovn-secondary-network"]
-= Connecting a virtual machine to an OVN-Kubernetes secondary network
+= Connecting a virtual machine to an OVN-Kubernetes layer 2 secondary network
 include::_attributes/common-attributes.adoc[]
 :context: virt-connecting-vm-to-ovn-secondary-network
 
@@ -13,35 +13,26 @@ A `layer2` topology connects workloads by a cluster-wide logical switch. The OVN
 endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 
 ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
-You can connect a virtual machine (VM) to an OVN-Kubernetes secondary network. {VirtProductName} supports the `layer2` and `localnet` topologies for OVN-Kubernetes.
+You can connect a virtual machine (VM) to an OVN-Kubernetes `layer2` secondary network by using the CLI. 
 
-* A `layer2` topology connects workloads by a cluster-wide logical switch. The OVN-Kubernetes Container Network Interface (CNI) plugin uses the Geneve (Generic Network Virtualization Encapsulation) protocol to create an overlay network between nodes. You can use this overlay network to connect VMs on different nodes, without having to configure any additional physical networking infrastructure.
-
-* A `localnet` topology connects the secondary network to the physical underlay. This enables both east-west cluster traffic and access to services running outside the cluster, but it requires additional configuration of the underlying Open vSwitch (OVS) system on cluster nodes.
+A `layer2` topology connects workloads by a cluster-wide logical switch. The OVN-Kubernetes Container Network Interface (CNI) plugin uses the Geneve (Generic Network Virtualization Encapsulation) protocol to create an overlay network between nodes. You can use this overlay network to connect VMs on different nodes, without having to configure any additional physical networking infrastructure.
 
 [NOTE]
 ====
-An OVN-Kubernetes secondary network is compatible with the xref:../../networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc#compatibility-with-multi-network-policy_configuring-additional-network[multi-network policy API] which provides the `MultiNetworkPolicy` custom resource definition (CRD) to control traffic flow to and from VMs. You can use the `ipBlock` attribute to define network policy ingress and egress rules for specific CIDR blocks.
+An OVN-Kubernetes secondary network is compatible with the xref:../../networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc#compatibility-with-multi-network-policy_configuring-additional-network[multi-network policy API] which provides the `MultiNetworkPolicy` custom resource definition (CRD) to control traffic flow to and from VMs. You must use the `ipBlock` attribute to define network policy ingress and egress rules for specific CIDR blocks. You cannot use pod or namespace selectors for virtualization workloads.
 ====
 endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 
-To configure an OVN-Kubernetes secondary network and attach a VM to that network, perform the following steps:
+To configure an OVN-Kubernetes `layer2` secondary network and attach a VM to that network, perform the following steps:
 
-. xref:../../virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc#virt-connecting-vm-to-ovn-secondary-network[Configure an OVN-Kubernetes secondary network] by creating a network attachment definition (NAD).
-ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
-+
-[NOTE]
-====
-For `localnet` topology, you must xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc#configuration-localnet-switched-topology_configuring-additional-network-ovnk[configure an OVS bridge] by creating a `NodeNetworkConfigurationPolicy` object before creating the NAD.
-====
-endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
+. xref:../../virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc#virt-connecting-vm-to-ovn-secondary-network[Configure an OVN-Kubernetes layer 2 secondary network].
 
-. xref:../../virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc#attaching-vm-to-ovn-secondary-nw[Connect the VM to the OVN-Kubernetes secondary network] by adding the network details to the VM specification.
+. xref:../../virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc#attaching-vm-to-ovn-secondary-nw[Connect the VM to the OVN-Kubernetes layer 2 secondary network].
 
 [id="creating-ovn-nad_{context}"]
-== Creating an OVN-Kubernetes NAD
+== Creating an OVN-Kubernetes layer 2 NAD
 
-You can create an OVN-Kubernetes network attachment definition (NAD) by using the {product-title} web console or the CLI.
+You can create an OVN-Kubernetes network attachment definition (NAD) for the layer 2 network topology by using the {product-title} web console or the CLI.
 
 [NOTE]
 ====
@@ -50,20 +41,20 @@ Configuring IP address management (IPAM) by specifying the `spec.config.ipam.sub
 
 include::modules/virt-creating-layer2-nad-cli.adoc[leveloffset=+2]
 
-ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
-include::modules/virt-creating-localnet-nad-cli.adoc[leveloffset=+2]
-endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
+//ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
+//include::modules/virt-creating-localnet-nad-cli.adoc[leveloffset=+2]
+//endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 
 include::modules/virt-creating-nad-l2-overlay-console.adoc[leveloffset=+2]
 
-ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
-include::modules/virt-creating-nad-localnet-console.adoc[leveloffset=+2]
-endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
+//ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
+//include::modules/virt-creating-nad-localnet-console.adoc[leveloffset=+2]
+//endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[]
 
 [id="attaching-vm-to-ovn-secondary-nw"]
-== Attaching a virtual machine to the OVN-Kubernetes secondary network
+== Attaching a virtual machine to the OVN-Kubernetes layer 2 secondary network
 
-You can attach a virtual machine (VM) to the OVN-Kubernetes secondary network interface by using the {product-title} web console or the CLI.
+You can attach a virtual machine (VM) to the OVN-Kubernetes layer 2 secondary network interface by using the {product-title} web console or the CLI.
 
 include::modules/virt-attaching-vm-to-ovn-secondary-nw-cli.adoc[leveloffset=+2]
 

diff --git a/virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc b/virt/vm_networking/virt-connecting-vm-to-primary-udn.adoc
@@ -28,10 +28,6 @@ You must consider the following limitations before implementing a primary UDN:
 * You cannot use headless services to access a VM.
 * You cannot define readiness and liveness probes to configure VM health checks.
 
-[NOTE]
-====
-{VirtProductName} currently does not support secondary user-defined networks.
-====
 
 [id="creating-primary-udn-web_{context}"]
 == Creating a primary user-defined network by using the web console

diff --git a/virt/vm_networking/virt-connecting-vm-to-secondary-udn.adoc b/virt/vm_networking/virt-connecting-vm-to-secondary-udn.adoc
@@ -0,0 +1,29 @@
+:_mod-docs-content-type: ASSEMBLY                               
+[id="virt-connecting-vm-to-secondary-udn"]                                    
+= Connecting a virtual machine to a secondary localnet user-defined network                                                
+include::_attributes/common-attributes.adoc[]                   
+:context: virt-connecting-vm-to-secondary-udn                                    
+
+toc::[]
+
+You can connect a virtual machine (VM) to an OVN-Kubernetes localnet secondary network by using the CLI. Cluster administrators can use the `ClusterUserDefinedNetwork` (CUDN) custom resource definition (CRD) to create a shared OVN-Kubernetes network across multiple namespaces.
+
+An OVN-Kubernetes secondary network is compatible with the xref:../../networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc#compatibility-with-multi-network-policy_configuring-additional-network[multi-network policy API] which provides the `MultiNetworkPolicy` custom resource definition (CRD) to control traffic flow to and from VMs. 
+
+[IMPORTANT]
+====
+You must use the `ipBlock` attribute to define network policy ingress and egress rules for specific CIDR blocks. Using pod or namespace selector policy peers is not supported.
+====
+
+A localnet topology connects the secondary network to the physical underlay. This enables both east-west cluster traffic and access to services running outside the cluster, but it requires additional configuration of the underlying Open vSwitch (OVS) system on cluster nodes.
+
+include::modules/virt-creating-secondary-localnet-udn.adoc[leveloffset=+1]
+
+include::modules/virt-creating-secondary-udn-namespace.adoc[leveloffset=+1]
+
+include::modules/virt-attaching-vm-to-secondary-udn.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+* xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-cudn_about-user-defined-networks[About the `ClusterUserDefinedNetwork` CR]