Merge pull request #89436 from dfitzmau/DIAGRAMS-500-17

DIAGRAMS-500-17

Author: dfitzmau

images/527-OpenShift-UDN-isolation-012025.png

@@ -9,14 +9,22 @@ 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.
+Before the implementation of user-defined networks (UDN), the OVN-Kubernetes CNI plugin for {product-title} only supported a Layer 3 topology on the primary or _main_ network. Due to Kubernetes design principles: all pods are attached to the main network, all pods communicate with each other by their IP addresses, and inter-pod traffic is restricted according to network policy.
 
-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.
+UDN improves the flexibility and segmentation capabilities of the default Layer 3 topology for a Kubernetes pod network by enabling custom Layer 2, Layer 3, and localnet network segments, where all these segments are isolated by default. These segments act as either primary or secondary networks for container pods and virtual machines that use the default OVN-Kubernetes CNI plugin. 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}.
+Support for the Localnet topology on both primary and secondary networks will be added in a future version of {product-title}.
 ====
+
+A cluster administrator can use a UDN to create and define additional networks that span multiple namespaces at the cluster level by leveraging the `ClusterUserDefinedNetwork` custom resource (CR). Additionally, a cluster administrator or a cluster user can use a UDN to define additional networks at the namespace level with the `UserDefinedNetwork` CR.
+
+The following diagram shows four cluster namespaces, where each namespace has a single assigned user-defined network (UDN), and each UDN has an assigned custom subnet for its pod IP allocations. The OVN-Kubernetes handles any overlapping UDN subnets. Without using the Kubernetes network policy, a pod attached to a UDN can communicate with other pods in that UDN. By default, these pods are isolated from communicating with pods that exist in other UDNs. For microsegmentation, you can apply network policy within a UDN. You can assign one or more UDNs to a namespace, with a limitation of only one primary UDN to a namespace, and one or more namespaces to a UDN.
+
+.Namespace isolation using a UserDefinedNetwork CR
+image::527-OpenShift-UDN-isolation-012025.png[The namespace isolation concept in a user-defined network (UDN)]
+
 ////
 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).