OSDOCS-11974:reorg of multi nwt docs

trying xref fix

topics map rebase

modularizes benefits for mulit nwt docs

Addresses Suryas comments

Commit three

_topic_maps/_topic_map.yml

@@ -1513,22 +1513,38 @@ Topics:
   Topics:
   - Name: Understanding multiple networks
     File: understanding-multiple-networks
-  - Name: Understanding user defined networks
+  - Name: Primary networks
-    File: understanding-user-defined-network
+    Dir: primary_networks
-  - Name: Configuring an additional network
+    Distros: openshift-enterprise, openshift-origin
-    File: configuring-additional-network
+    Topics:
+    - Name: UserDefinedNetwork CR
+      File: about-user-defined-networks
+    - Name: NetworkAttachmentDefinition CR
+      File: about-primary-nwt-nad
+  - Name: Secondary networks
+    Dir: secondary_networks
+    Distros: openshift-enterprise, openshift-origin
+    Topics:
+    - Name: Creating secondary networks on OVN-Kubernetes
+      File: creating-secondary-nwt-ovnk
+    - Name: Creating secondary networks with other CNI plugins
+      File: creating-secondary-nwt-other-cni
+    - Name: Attaching a pod to an additional network
+      File: attaching-pod
+    - Name: Configuring multi-network policies
+      File: configuring-multi-network-policy
+    - Name: Removing a pod from an additional network
+      File: removing-pod
+    - Name: Editing an additional network
+      File: editing-additional-network
+    - Name: Configuring IP address assignment for secondary networks
+      File: configuring-ip-secondary-nwt
+    - Name: Configuring the master interface in the container network namespace
+      File: configuring-master-interface
+    - Name: Removing an additional network
+      File: removing-additional-network
   - Name: About virtual routing and forwarding
     File: about-virtual-routing-and-forwarding
-  - Name: Configuring multi-network policy
-    File: configuring-multi-network-policy
-  - Name: Attaching a pod to an additional network
-    File: attaching-pod
-  - Name: Removing a pod from an additional network
-    File: removing-pod
-  - Name: Editing an additional network
-    File: edit-additional-network
-  - Name: Removing an additional network
-    File: remove-additional-network
   - Name: Assigning a secondary network to a VRF
     File: assigning-a-secondary-network-to-a-vrf
 - Name: Hardware networks

installing/installing_openstack/installing-openstack-installer-ovs-dpdk.adoc

@@ -59,9 +59,9 @@ include::modules/networking-osp-enabling-vfio-noiommu.adoc[leveloffset=+1]
 include::modules/installation-osp-dpdk-binding-vfio-pci.adoc[leveloffset=+1]
 include::modules/installation-osp-dpdk-exposing-host-interface.adoc[leveloffset=+1]
 
-.Additional resources
+.Additional resource
 
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-host-device-object_configuring-additional-network[Creating an additional network attachment with the Cluster Network Operator]
+* xref:../../networking/multiple_networks/primary_networks/creating-primary-nad.adoc#creating-primary-nad[Creating an additional network attachment with the Cluster Network Operator]
 
 The cluster is installed and prepared for configuration. You must now perform the OVS-DPDK configuration tasks in <<next-steps_installing-openstack-installer-ovs-dpdk, Next steps>>.
 

modules/nw-nad-cr.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+//
+// * networking/multiple_networks/creating-primary-nad.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="nw-nad-cr_{context}"]
+== Configuration for an additional network attachment
+
+An additional network is configured by using the `NetworkAttachmentDefinition` API in the `k8s.cni.cncf.io` API group.
+
+The configuration for the API is described in the following table:
+
+.`NetworkAttachmentDefinition` API fields
+[cols=".^3,.^2,.^5",options="header"]
+|====
+|Field|Type|Description
+
+|`metadata.name`
+|`string`
+|The name for the additional network.
+
+|`metadata.namespace`
+|`string`
+|The namespace that the object is associated with.
+
+|`spec.config`
+|`string`
+|The CNI plugin configuration in JSON format.
+
+|====

modules/nw-udn-benefits.adoc

@@ -0,0 +1,32 @@
+//module included in the following assembly:
+//
+// *networking/multiple_networks/about-user-defined-networks.adoc
+:_mod-docs-content-type: REFERENCE
+[id="nw-udn-benefits_{context}"]
+= Benefits of a user-defined network
+
+User-defined networks provide the following benefits:
+
+. Enhanced network isolation for security
++
+* **Tenant isolation**: Namespaces can have their own isolated primary network, similar to how tenants are isolated in {rh-openstack-first}. This improves security by reducing the risk of cross-tenant traffic.
+
+. Network flexibility
++
+* **Layer 2 and layer 3 support**: Cluster administrators can configure primary networks as layer 2 or layer 3 network types. This provides the flexibility of a secondary network to the primary network.
+
+. Simplified network management
++
+* **Reduced network configuration complexity**: With user-defined networks, the need for complex network policies are eliminated because isolation can be achieved by grouping workloads in different networks.
+
+. Advanced capabilities
++
+* **Consistent and selectable IP addressing**: Users can specify and reuse IP subnets across different namespaces and clusters, providing a consistent networking environment.
++
+* **Support for multiple networks**: The user-defined networking feature allows administrators to connect multiple namespaces to a single network, or to create distinct networks for different sets of namespaces.
+
+. Simplification of application migration from {rh-openstack-first}
++
+* **Network parity**: With user-defined networking, the migration of applications from OpenStack to {product-title} is simplified by providing similar network isolation and configuration options.
+
+Developers and administrators can create a user-defined network that is namespace scoped using the custom resource. An overview of the process is: create a namespace, create and configure the custom resource, create pods in the namespace.

networking/hardware_networks/about-sriov.adoc

@@ -90,7 +90,7 @@ include::modules/nw-sriov-huge-pages.adoc[leveloffset=+2]
 [id="configure-multi-networks-additional-resources"]
 == Additional resources
 
-* xref:../../networking/multiple_networks/configuring-multi-network-policy.adoc#configuring-multi-network-policy[Configuring multi-network policy]
+* xref:../../networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc#configuring-multi-network-policy[Configuring multi-network policy]
 
 [id="about-sriov-next-steps"]
 == Next steps

networking/hardware_networks/configuring-sriov-ib-attach.adoc

@@ -21,7 +21,7 @@ include::modules/nw-multus-configure-dualstack-ip-address.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../networking/multiple_networks/attaching-pod.html#nw-multus-add-pod_attaching-pod[Attaching a pod to an additional network]
+* xref:../../networking/multiple_networks/secondary_networks/attaching-pod.adoc#attaching-pod[Attaching a pod to an additional network]
 
 // Configuring SR-IOV additional network
 include::modules/nw-sriov-network-attachment.adoc[leveloffset=+1]

networking/hardware_networks/configuring-sriov-net-attach.adoc

@@ -17,7 +17,7 @@ include::modules/nw-multus-configure-dualstack-ip-address.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../networking/multiple_networks/attaching-pod.html#nw-multus-add-pod_attaching-pod[Attaching a pod to an additional network]
+* xref:../../networking/multiple_networks/secondary_networks/attaching-pod.adoc#attaching-pod[Attaching a pod to an additional network]
 
 include::modules/nw-sriov-network-attachment.adoc[leveloffset=+1]
 

networking/hardware_networks/configuring-sriov-qinq-support.adoc

@@ -15,6 +15,6 @@ include::modules/nw-sriov-about-qinq.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-vlan-object_configuring-additional-network[Configuration for an VLAN additional network]
+xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-vlan-object_configuring-additional-network-cni[Configuration for an VLAN additional network]
 
 include::modules/nw-configuring-qinq-sriov-proc.adoc[leveloffset=+1]

networking/hardware_networks/using-dpdk-and-rdma.adoc

@@ -22,7 +22,7 @@ include::modules/nw-running-dpdk-rootless-tap.adoc[leveloffset=+1]
 [role="_additional-resources"]
 .Additional resources
 
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-enable-container_use_devices_configuring-additional-network[Enabling the container_use_devices boolean]
+// I can't seem to find this in 4.16 or 4.15 * xr3f:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-enable-container_use_devices_configuring-additional-network[Enabling the container_use_devices boolean]
 
 * xref:../../scalability_and_performance/low_latency_tuning/cnf-tuning-low-latency-nodes-with-perf-profile.adoc#cnf-create-performance-profiles[Creating a performance profile]
 
@@ -68,9 +68,7 @@ include::modules/nw-openstack-hw-offload-testpmd-pod.adoc[leveloffset=+1]
 * xref:../../networking/networking_operators/sr-iov-operator/installing-sriov-operator.adoc#installing-sriov-operator[Installing the SR-IOV Network Operator]
 
 * xref:../../networking/hardware_networks/configuring-sriov-device.adoc#nw-sriov-networknodepolicy-object_configuring-sriov-device[Configuring an SR-IOV network device]
-
+* xref:../../networking/multiple_networks/secondary_networks/configuring-ip-secondary-nwt.adoc#nw-multus-whereabouts_configuring-additional-network[Dynamic IP address assignment configuration with Whereabouts]
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-whereabouts_configuring-additional-network[Dynamic IP address assignment configuration with Whereabouts]
-
 * xref:../../scalability_and_performance/low_latency_tuning/cnf-provisioning-low-latency-workloads.adoc#disabling-interrupt-processing-for-individual-pods_cnf-provisioning-low-latency[Disabling interrupt processing for individual pods]
 
 * xref:../../networking/hardware_networks/configuring-sriov-net-attach.adoc#configuring-sriov-net-attach[Configuring an SR-IOV Ethernet network attachment]

networking/multiple_networks/about-virtual-routing-and-forwarding.adoc

@@ -1,6 +1,6 @@
 :_mod-docs-content-type: ASSEMBLY
-[id="about-virtual-routing-and-forwarding"]
+[id="virtual-routing-and-forwarding"]
-= About virtual routing and forwarding
+= Virtual routing and forwarding
 include::_attributes/common-attributes.adoc[]
 :context: about-virtual-routing-and-forwarding
 

networking/multiple_networks/primary_networks/_attributes

@@ -0,0 +1 @@
+../../_attributes/

networking/multiple_networks/primary_networks/about-primary-nwt-nad.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="about-primary-nwt-nad"]
+= Creating primary networks using a NetworkAttachmentDefinition
+include::_attributes/common-attributes.adoc[]
+:context: understanding-multiple-networks
+
+toc::[]
+
+The following sections explain how to create and manage additional primary networks using the `NetworkAttachmentDefinition` (NAD) resource.
+
+[id="{context}_approaches-managing-additional-network"]
+== Approaches to managing an additional network
+
+You can manage the life cycle of an additional network created by NAD with one of the following two approaches:
+
+* By modifying the Cluster Network Operator (CNO) configuration. With this method, the CNO automatically creates and manages the `NetworkAttachmentDefinition` object. In addition to managing the object lifecycle, the CNO ensures that a DHCP is available for an additional network that uses a DHCP assigned IP address.
+
+* By applying a YAML manifest. With this method, you can manage the additional network directly by creating an `NetworkAttachmentDefinition` object. This approach allows for the invocation of multiple CNI plugins in order to attach additional network interfaces in a pod.
+
+Each approach is mutually exclusive and you can only use one approach for managing an additional network at a time. For either approach, the additional network is managed by a Container Network Interface (CNI) plugin that you configure.
+
+[NOTE]
+====
+When deploying {product-title} nodes with multiple network interfaces on {rh-openstack-first} with OVN SDN, DNS configuration of the secondary interface might take precedence over the DNS configuration of the primary interface. In this case, remove the DNS nameservers for the the subnet ID that is attached to the secondary interface by running the following command:
+
+[source,terminal]
+----
+$ openstack subnet set --dns-nameserver 0.0.0.0 <subnet_id>
+----
+====
+
+include::modules/nw-multus-create-network.adoc[leveloffset=+1]
+
+include::modules/nw-nad-cr.adoc[leveloffset=+1]
+
+include::modules/nw-multus-create-network-apply.adoc[leveloffset=+1]

networking/multiple_networks/primary_networks/about-user-defined-networks.adoc

@@ -0,0 +1,59 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="about-user-defined-networks"]
+= About user-defined networks
+include::_attributes/common-attributes.adoc[]
+:context: about-user-defined-networks
+
+toc::[]
+
+:featurename: `UserDefinedNetwork`
+include::snippets/technology-preview.adoc[]
+
+Before the implementation of user-defined networks (UDN), the OVN-Kubernetes CNI plugin only supported a Layer 3 topology on the primary, or main, network that all pods are attached to. This allowed for network models where all pods in the cluster were part of the same global Layer 3 network, but restricted the ability to customize primary network configurations.
+
+User-defined networks provide cluster administrators and users with highly customizable network configuration options for both primary and secondary network types. With UDNs, administrators can create tailored network topologies with enhanced isolation, IP address management for workloads, and advanced networking features. Supporting both Layer 2 and Layer 3 topology types, UDNs enable a wide range of network architectures and topologies, enhancing network flexibility, security, and performance.
+
+[NOTE]
+====
+* Support for the Localnet topology on both primary and secondary networks will be added in a future version of {product-title}.
+====
+
+Unlike NADs, which are only namespaced scope, UDNs offer administrators the ability to create and define additional networks spanning multiple namespaces at the cluster level by leveraging the `ClusterUserDefinedNetwork` custom resource (CR). UDNs also offer both administrators and users the ability to define additional networks at the namespace level with the `UserDefinedNetwork` CR. 
+
+The following sections further emphasize the benefits and limitations of user-defined networks, the best practices when creating a `ClusterUserDefinedNetwork` or `UserDefinedNetwork` custom resource, how to create the custom resource, and additional configuration details that might be relevant to your deployment.
+
+// Looks like this may be out for 4.17, but in for 4.18 as of 8/19/24
+//. Ingress and egress support
+//+
+//* **Support for ingress and egress traffic**: Cluster ingress and egress traffic is supported for both primary and secondary networks.
+//* **Support for ingress and egress features**: User-defined networks support support the following ingress and egress features:
+//+
+//** EgressQoS
+//** EgressService
+//** EgressIP
+//** Load balancer and NodePort services, as well as services with external IPs.
+
+//benefits of UDN
+include::modules/nw-udn-benefits.adoc[leveloffset=+1]
+
+//Limitations that users should consider for UDN.
+include::modules/nw-udn-limitations.adoc[leveloffset=+1]
+
+//Best practices for using UDN.
+include::modules/nw-udn-best-practices.adoc[leveloffset=+1]
+
+//How to implement the UDN API on a cluster.
+include::modules/nw-udn-cr.adoc[leveloffset=+1]
+
+//Explanation of optional config details
+include::modules/nw-udn-additional-config-details.adoc[leveloffset=+1]
+
+//Support matrix for UDN
+//include::modules
+
+//Examples for Layer2 and Layer3
+//include::modules/nw-udn-examples.adoc[leveloffset=+2]
+
+//[role="_additional-resources"]
+//== Additional resources
+// * xr3f../virtual docs that point to live migration of vms for 4.18's GA.

networking/multiple_networks/primary_networks/images

@@ -0,0 +1 @@
+../../images/

networking/multiple_networks/primary_networks/modules

@@ -0,0 +1 @@
+../../modules/

networking/multiple_networks/primary_networks/snippets

@@ -0,0 +1 @@
+../../snippets/

networking/multiple_networks/secondary_networks/_attributes

@@ -0,0 +1 @@
+../../_attributes/

networking/multiple_networks/secondary_networks/configuring-ip-secondary-nwt.adoc

@@ -0,0 +1,17 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configuring-ip-secondary-nwt"]
+= Configuring IP address assignment on secondary networks
+include::_attributes/common-attributes.adoc[]
+:context: configuring-additional-network
+
+toc::[]
+
+The following sections provide instructions and information for how to configure IP address assignments for secondary networks.
+
+include::modules/nw-multus-ipam-object.adoc[leveloffset=+1]
+
+include::modules/nw-multus-creating-whereabouts-reconciler-daemon-set.adoc[leveloffset=+2]
+
+include::modules/nw-multus-configuring-whereabouts-ip-reconciler-schedule.adoc[leveloffset=+2]
+
+include::modules/nw-multus-configure-dualstack-ip-address.adoc[leveloffset=+2]

networking/multiple_networks/secondary_networks/configuring-master-interface.adoc

@@ -0,0 +1,15 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configuring-master-interface-secondary-nwt"]
+= Configuring the master interface in the container network namespace
+include::_attributes/common-attributes.adoc[]
+:context: configuring-additional-network
+
+toc::[]
+
+The following section provides instructions and information for how to create and manage a MAC-VLAN, IP-VLAN, and VLAN subinterface based on a master interface.
+
+include::modules/nw-about-configuring-master-interface-container.adoc[leveloffset=+1]
+
+include::modules/nw-multus-create-multiple-vlans-sriov.adoc[leveloffset=+2]
+
+include::modules/nw-multus-create-master-interface-bridge-cni.adoc[leveloffset=+2]

networking/multiple_networks/secondary_networks/configuring-multi-network-policy.adoc

@@ -6,6 +6,10 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+Administrators can use the `MultiNetworkPolicy` API to create multiple network policies that manage traffic for pods attached to secondary networks. For example, you can create policies that allow or deny traffic based on specific ports, IPs/ranges, or labels.
+
+Multi-network policies can be used to manage traffic on secondary networks in the cluster. They cannot managed the cluster's default network or primary network of user-defined networks. 
+
 As a cluster administrator, you can configure a multi-network policy for any of the following network types:
 
 * Single-Root I/O Virtualization (SR-IOV)
@@ -47,7 +51,7 @@ include::modules/nw-networkpolicy-allow-application-particular-namespace.adoc[le
 [role="_additional-resources"]
 == Additional resources
 
-* xref:../../networking/network_security/network_policy/about-network-policy.adoc#about-network-policy[About network policy]
+* xref:../../../networking/network_security/network_policy/about-network-policy.adoc#about-network-policy[About network policy]
-* xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks]
+* xref:../../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks]
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-macvlan-object_configuring-additional-network[Configuring a macvlan network]
+* xref:../../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-macvlan-object_configuring-additional-network-cni[Configuring a macvlan network]
-* xref:../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device]
+* xref:../../../networking/hardware_networks/configuring-sriov-device.adoc#configuring-sriov-device[Configuring an SR-IOV network device]

networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc

@@ -0,0 +1,32 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="creating-secondary-networks-other-cni"]
+= Creating secondary networks with other CNI plugins
+include::_attributes/common-attributes.adoc[]
+:context: configuring-additional-network-cni
+
+toc::[]
+
+The specific configuration fields for additional networks are described in the following sections.
+
+// Configuration for a bridge additional network
+include::modules/nw-multus-bridge-object.adoc[leveloffset=+1]
+
+// Configuration for a host device additional network
+include::modules/nw-multus-host-device-object.adoc[leveloffset=+1]
+
+// Configuration for an VLAN additional network
+include::modules/nw-multus-vlan-object.adoc[leveloffset=+1]
+
+// Configuration for an ipvlan additional network
+include::modules/nw-multus-ipvlan-object.adoc[leveloffset=+1]
+
+// Configuration for a macvlan additional network
+include::modules/nw-multus-macvlan-object.adoc[leveloffset=+1]
+
+// Configuration for a TAP additional network
+include::modules/nw-multus-tap-object.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* For more information about enabling an SELinux boolean on a node, see xref:../../../nodes/nodes/nodes-nodes-managing.adoc#nodes-nodes-working-setting-booleans_nodes-nodes-managing[Setting SELinux booleans].

networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc

@@ -0,0 +1,32 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="creating-secondary-networks-ovnk"]
+= Creating secondary networks on OVN-Kubernetes
+include::_attributes/common-attributes.adoc[]
+:context: configuring-additional-network-ovnk
+
+toc::[]
+
+As a cluster administrator, you can configure an additional secondary network for your cluster using the `NetworkAttachmentDefinition` (NAD) resource. 
+
+[NOTE]
+====
+Support for user-defined networks as a secondary network will be added in a future version of {product-title}.
+====
+
+//For more information, see the xr3f:../networking/multiple_networks/secondary_networks/understanding-user-defined-network.adoc#understanding-user-defined-network[Understanding user defined networks]
+
+include::modules/configuring-ovnk-additional-networks.adoc[leveloffset=+1]
+
+include::modules/configuration-ovnk-network-plugin-json-object.adoc[leveloffset=+2]
+
+include::modules/configuration-ovnk-multi-network-policy.adoc[leveloffset=+2]
+
+include::modules/configuring-localnet-switched-topology.adoc[leveloffset=+2]
+
+include::modules/configuring-layer-two-switched-topology.adoc[leveloffset=+3]
+
+//include::modules/configuring-layer-three-routed-topology.adoc[leveloffset=+2]
+
+include::modules/configuring-pods-secondary-network.adoc[leveloffset=+2]
+
+include::modules/configuring-pods-static-ip.adoc[leveloffset=+2]

networking/multiple_networks/secondary_networks/images

@@ -0,0 +1 @@
+../../images/

networking/multiple_networks/secondary_networks/modules

@@ -0,0 +1 @@
+../../modules/

networking/multiple_networks/secondary_networks/snippets

@@ -0,0 +1 @@
+../../snippets/

networking/multiple_networks/understanding-multiple-networks.adoc

@@ -6,57 +6,65 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-In Kubernetes, container networking is delegated to networking plugins that
+By default, OVN-Kubernetes serves as the Container Network Interface (CNI) of an {product-title} cluster. With OVN-Kubernetes as the default CNI of a cluster, {product-title} administrators or users can leverage xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-user-defined-networks[user-defined networks (UDNs)] or xref:../../networking/multiple_networks/primary_networks/about-primary-nwt-nad.adoc#understanding-multiple-networks[NetworkAttachmentDefinition (NADs)] to create one, or multiple, default networks that handle all ordinary network traffic of the cluster. Both user-defined networks and Network Attachment Definitions can serve as the following network types:
-implement the Container Network Interface (CNI).
 
-{product-title} uses the Multus CNI plugin to allow chaining of CNI plugins.
+* *Primary networks*: Act as the primary network for the pod. By default, all traffic passes through the primary network unless a pod route is configured to send traffic through other networks.
-During cluster installation, you configure your _default_ pod network. The
+
-default network handles all ordinary network traffic for the cluster. You can
+* *Secondary networks*: Act as additional, non-default networks for a pod. Secondary networks provide separate interfaces dedicated to specific traffic types or purposes. Only pod traffic that is explicitly configured to use a secondary network is routed through its interface.
-define an _additional network_ based on the available CNI plugins and attach
+
-one or more of these networks to your pods. You can define more than one
+However, during cluster installation, {product-title} administrators can configure alternative default secondary pod networks by leveraging the Multus CNI plugin. With Multus, multiple CNI plugins such as ipvlan, macvlan, or Network Attachment Definitions can be used together to serve as secondary networks for pods.
-additional network for your cluster, depending on your needs. This gives you
+
-flexibility when you configure pods that deliver network functionality, such as
+[NOTE]
-switching or routing.
+====
+User-defined networks are only available when OVN-Kubernetes is used as the CNI. They are not supported for use with other CNIs.
+====
+
+You can define an additional network based on the available CNI plugins and attach one or more of these networks to your pods. You can define more than one additional network for your cluster depending on your needs. This gives you flexibility when you configure pods that deliver network functionality, such as switching or routing.
+
+For a complete list of supported CNI plugins, see xref:additional-networks-provided_understanding-multiple-networks["Additional networks in {product-title}"].
+
+For information about user-defined networks, see xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-user-defined-networks[About user-defined networks (UDNs)].
+
+For information about Network Attachment Definitions, see xref:../../networking/multiple_networks/primary_networks/about-primary-nwt-nad.adoc#understanding-multiple-networks[Creating primary networks using a NetworkAttachmentDefinition].
 
 [id="additional-network-considerations"]
 == Usage scenarios for an additional network
 
-You can use an additional network in situations where network isolation is
+You can use an additional network in situations where network isolation is needed, including data plane and control plane separation. Isolating network traffic is useful for the following performance and security reasons:
-needed, including data plane and control plane separation. Isolating network
-traffic is useful for the following performance and security reasons:
 
-Performance:: You can send traffic on two different planes to manage
+. Performance
-how much traffic is along each plane.
++
-Security:: You can send sensitive traffic onto a network plane that is managed
+**Traffic management**: You can send traffic on two different planes to manage how much traffic is along each plane.
-specifically for security considerations, and you can separate private data that
-must not be shared between tenants or customers.
 
-All of the pods in the cluster still use the cluster-wide default network
+. Security
-to maintain connectivity across the cluster. Every pod has an `eth0` interface
++
-that is attached to the cluster-wide pod network. You can view the interfaces
+**Network isolation**: You can send sensitive traffic onto a network plane that is managed specifically for security considerations, and you can separate private data that must not be shared between tenants or customers.
-for a pod by using the `oc exec -it <pod_name> \-- ip a` command. If you
+
-add additional network interfaces that use Multus CNI, they are named `net1`,
+All of the pods in the cluster still use the cluster-wide default network to maintain connectivity across the cluster. Every pod has an `eth0` interface that is attached to the cluster-wide pod network. You can view the interfaces for a pod by using the `oc exec -it <pod_name> \-- ip a` command. If you add additional network interfaces that use Multus CNI, they are named `net1`,
 `net2`, ..., `netN`.
 
-To attach additional network interfaces to a pod, you must create configurations that define how the interfaces are attached. You specify each interface by using a `NetworkAttachmentDefinition` custom resource (CR). A CNI configuration inside each of these CRs defines how that interface is created.
+To attach additional network interfaces to a pod, you must create configurations that define how the interfaces are attached. You specify each interface by using either a `UserDefinedNetwork` custom resource (CR) or a `NetworkAttachmentDefinition` CR. A CNI configuration inside each of these CRs defines how that interface is created.
 
-[id="additional-networks-provided"]
+For more information about creating a `UserDefinedNetwork` CR, see xref:../../networking/multiple_networks/primary_networks/about-user-defined-networks.adoc#about-user-defined-networks[About user-defined networks].
+
+For more information about creating a NetworkAttachmentDefinition CR, see xref:../../networking/multiple_networks/primary_networks/about-primary-nwt-nad.adoc#understanding-multiple-networks[Creating primary networks using a NetworkAttachmentDefinition].
+
+[id="additional-networks-provided_{context}"]
 == Additional networks in {product-title}
 
 {product-title} provides the following CNI plugins for creating additional
 networks in your cluster:
 
- * *bridge*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-bridge-object_configuring-additional-network[Configure a bridge-based additional network]
+* *bridge*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-bridge-object_configuring-additional-network-cni[Configure a bridge-based additional network] to allow pods on the same host to communicate with each other and the host.
- to allow pods on the same host to communicate with each other and the host.
 
-* *host-device*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-host-device-object_configuring-additional-network[Configure a host-device additional network] to allow pods access to a physical Ethernet network device on the host system.
+* *host-device*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-host-device-object_configuring-additional-network-cni[Configure a host-device additional network] to allow pods access to a physical Ethernet network device on the host system.
 
- * *ipvlan*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-ipvlan-object_configuring-additional-network[Configure an ipvlan-based additional network] to allow pods on a host to communicate with other hosts and pods on those hosts, similar to a macvlan-based additional network. Unlike a macvlan-based additional network, each pod shares the same MAC address as the parent physical network interface.
+* *ipvlan*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-ipvlan-object_configuring-additional-network-cni[Configure an ipvlan-based additional network] to allow pods on a host to communicate with other hosts and pods on those hosts, similar to a macvlan-based additional network. Unlike a macvlan-based additional network, each pod shares the same MAC address as the parent physical network interface.
 
-* *vlan*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-vlan-object_configuring-additional-network[Configure a vlan-based additional network] to allow VLAN-based network isolation and connectivity for pods.
+* *vlan*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-vlan-object_configuring-additional-network-cni[Configure a VLAN-based additional network] to allow VLAN-based network isolation and connectivity for pods.
 
- * *macvlan*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-macvlan-object_configuring-additional-network[Configure a macvlan-based additional network] to allow pods on a host to communicate with other hosts and pods on those hosts by using a physical network interface. Each pod that is attached to a macvlan-based additional network is provided a unique MAC address.
+* *macvlan*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-macvlan-object_configuring-additional-network-cni[Configure a macvlan-based additional network] to allow pods on a host to communicate with other hosts and pods on those hosts by using a physical network interface. Each pod that is attached to a macvlan-based additional network is provided a unique MAC address.
 
-  * *tap*: xref:../../networking/multiple_networks/configuring-additional-network.adoc#nw-multus-tap-object_configuring-additional-network[Configure a tap-based additional network] to create a tap device inside the container namespace. A tap device enables user space programs to send and receive network packets.
+* *TAP*: xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-other-cni.adoc#nw-multus-tap-object_configuring-additional-network-cni[Configure a TAP-based additional network] to create a tap device inside the container namespace. A TAP device enables user space programs to send and receive network packets.
 
- * *SR-IOV*: xref:../../networking/hardware_networks/about-sriov.adoc#about-sriov[Configure an SR-IOV based additional network] to allow pods to attach to a virtual function (VF) interface on SR-IOV capable hardware on the host system.
+* *SR-IOV*: xref:../../networking/hardware_networks/about-sriov.adoc#about-sriov[Configure an SR-IOV based additional network] to allow pods to attach to a virtual function (VF) interface on SR-IOV capable hardware on the host system.

networking/multiple_networks/understanding-user-defined-network.adoc

@@ -1,71 +0,0 @@
-:_mod-docs-content-type: ASSEMBLY
-[id="understanding-user-defined-networks"]
-= Understanding user-defined networks
-include::_attributes/common-attributes.adoc[]
-:context: understanding-user-defined-networks
-
-toc::[]
-
-:featurename: `UserDefinedNetwork`
-include::snippets/technology-preview.adoc[]
-
-The OVN-Kubernetes CNI plugin supports `layer2`, `layer3`, and `localnet` topologies for secondary pod networks. However, for the primary network, or the main network that all pods are attached to, only a `layer3` topology is supported. This allows for network models where all pods in the cluster were part of the same global `layer3` network, but restricts the ability to customize primary network configurations.
-
-With user-defined networks, cluster administrators and users are offered highly customizable network configuration options that provide users with the ability to define their own network topologies, ensure network isolation, manage IP addressing for the workloads, and leverage advanced networking features. User-defined networks help enhance networking flexibility, security, and performance.
-
-User-defined networks provide the following benefits:
-
-. Enhanced network isolation
-+
-* **Tenant isolation**: Namespaces can have their own isolated primary network, similar to how tenants are isolated in {rh-openstack-first}. This improves security by reducing the risk of cross-tenant traffic.
-
-. Network flexibility
-+
-* **Layer 2 and layer 3 support**: Cluster administrators can configure primary networks as layer 2 or layer 3 network types. This provides the flexibility of a secondary network to the primary network.
-
-. Simplified network management
-+
-* **Reduced network configuration complexity**: With user-defined networks, the need for complex network policies are eliminated because isolation can be achieved by grouping workloads in different networks.
-
-. Advanced capabilities
-+
-* **Consistent and selectable IP addressing**: Users can specify and reuse IP subnets across different namespaces and clusters, providing a consistent networking environment.
-+
-* **Support for multiple networks**: The user-defined networking feature allows administrators to connect multiple namespaces to a single network, or to create distinct networks for different sets of namespaces.
-
-. Simplification of application migration from {rh-openstack-first}
-+
-* **Network parity**: With user-defined networking, the migration of applications from OpenStack to {product-title} is simplified by providing similar network isolation and configuration options.
-
-// Looks like this may be out for 4.17, but in for 4.18 as of 8/19/24
-//. Ingress and egress support
-//+
-//* **Support for ingress and egress traffic**: Cluster ingress and egress traffic is supported for both primary and secondary networks.
-//* **Support for ingress and egress features**: User-defined networks support support the following ingress and egress features:
-//+
-//** EgressQoS
-//** EgressService
-//** EgressIP
-//** Load balancer and NodePort services, as well as services with external IPs.
-
-//Limitations that users should consider for UDN.
-include::modules/nw-udn-limitations.adoc[leveloffset=+1]
-
-//Best practices for using UDN.
-include::modules/nw-udn-best-practices.adoc[leveloffset=+1]
-
-//How to implement the UDN API on a cluster.
-include::modules/nw-udn-cr.adoc[leveloffset=+1]
-
-//Explanation of optional config details
-include::modules/nw-udn-additional-config-details.adoc[leveloffset=+1]
-
-//Support matrix for UDN
-//include::modules
-
-//Examples for Layer2 and Layer3
-//include::modules/nw-udn-examples.adoc[leveloffset=+2]
-
-//[role="_additional-resources"]
-//== Additional resources
-// * xr3f../virtual docs that point to live migration of vms for 4.18's GA.

post_installation_configuration/post-install-network-configuration.adoc

@@ -23,7 +23,8 @@ For more information, see xref:../networking/networking_operators/cluster-networ
 * xref:../networking/network_security/configuring-ipsec-ovn.adoc#configuring-ipsec-ovn[Configuring IPsec encryption]
 * xref:../networking/network_security/network_policy/creating-network-policy.adoc#creating-network-policy[Create a network policy] or xref:../networking/network_security/network_policy/multitenant-network-policy.adoc#multitenant-network-policy[configure multitenant isolation with network policies]
 * xref:../scalability_and_performance/optimization/routing-optimization.adoc#routing-optimization[Optimizing routing]
-* xref:../networking/multiple_networks/configuring-additional-network.adoc#configuring-additional-network_configuration-additional-network-attachment[Configuration for an additional network attachment]
+//change this to point to UDN once docs are merged.
+* xref:../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks]
 
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
 [id="post-install-network-configuration-default-network-policies"]

virt/vm_networking/virt-connecting-vm-to-ovn-secondary-network.adoc

@@ -21,7 +21,7 @@ You can connect a virtual machine (VM) to an OVN-Kubernetes secondary network. {
 
 [NOTE]
 ====
-An OVN-Kubernetes secondary network is compatible with the xref:../../networking/multiple_networks/configuring-additional-network.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 can use the `ipBlock` attribute to define network policy ingress and egress rules for specific CIDR blocks.
 ====
 endif::openshift-rosa,openshift-dedicated[]
 
@@ -32,7 +32,7 @@ ifndef::openshift-rosa,openshift-dedicated[]
 +
 [NOTE]
 ====
-For `localnet` topology, you must xref:../../networking/multiple_networks/configuring-additional-network.adoc#configuring-additional-network_ovn-kubernetes-configuration-for-a-localnet-topology[configure an OVS bridge] by creating a `NodeNetworkConfigurationPolicy` object before creating the NAD.
+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[]
 
@@ -72,8 +72,7 @@ ifndef::openshift-rosa,openshift-dedicated[]
 [role="_additional-resources"]
 [id="additional-resources_virt-connecting-vm-to-ovn-secondary-network"]
 == Additional resources
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#configuration-ovnk-additional-networks_configuring-additional-network[Configuration for an OVN-Kubernetes additional network]
+* xref:../../networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc#configuration-ovnk-additional-networks_configuring-additional-network[Creating secondary networks on OVN-Kubernetes]
-* xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc#k8s-nmstate-about-the-k8s-nmstate-operator[Kubernetes NMState Operator]
+* xref:../../networking/networking_operators/k8s-nmstate-about-the-k8s-nmstate-operator.adoc#k8s-nmstate-about-the-k8s-nmstate-operator[About the Kubernetes NMState Operator]
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#configuring-additional-network_configuration-additional-network-interface[Configuration for an OVN-Kubernetes additional network mapping]
+* xref:../../networking/multiple_networks/primary_networks/about-primary-nwt-nad.adoc#understanding-multiple-networks[Creating primary networks using a NetworkAttachmentDefinition]
-* xref:../../networking/multiple_networks/configuring-additional-network.adoc#configuring-additional-network_configuration-additional-network-attachment[Configuration for an additional network attachment]
 endif::openshift-rosa,openshift-dedicated[]

virt/vm_networking/virt-networking-overview.adoc

@@ -57,7 +57,7 @@ You can expose a VM within the cluster or outside the cluster by creating a `Ser
 endif::openshift-rosa,openshift-dedicated[]
 // Hiding from ROSA/OSD until OSDOCS-3691 is merged
 ifdef::openshift-rosa,openshift-dedicated[]
-You can expose a VM within the cluster or outside the cluster by creating a `Service` object. 
+You can expose a VM within the cluster or outside the cluster by creating a `Service` object.
 endif::openshift-rosa,openshift-dedicated[]
 
 [id="secondary-network-config"]
@@ -101,7 +101,7 @@ ifndef::openshift-rosa,openshift-dedicated[]
 +
 [NOTE]
 ====
-For `localnet` topology, you must xref:../../networking/multiple_networks/configuring-additional-network.adoc#configuring-additional-network_ovn-kubernetes-configuration-for-a-localnet-topology[configure an OVS bridge] by creating a `NodeNetworkConfigurationPolicy` object before creating the NAD.
+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[]
 
@@ -192,7 +192,7 @@ The following table provides a comparison of features available when using the L
 |Available on Linux bridge CNI
 |Available on OVN-Kubernetes localnet
 
-|Layer 2 access to the underlay native network	
+|Layer 2 access to the underlay native network
 |Only on secondary network interface controllers (NICs)
 |Yes