Merge pull request #87694 from dfitzmau/DIAGRAMS-527

DIAGRAMS-527: Added the namespace isolation diagram to UDN docs

Author: dfitzmau

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

@@ -6,7 +6,7 @@
 [id="nw-udn-cr_{context}"]
 = Creating a UserDefinedNetwork custom resource
 
-The following procedure creates a user-defined network that is namespace scoped. Based upon your use case, create your request using either the `my-layer-two-udn.yaml` example for a `Layer2` topology type or the `my-layer-three-udn.yaml` example for a `Layer3` topology type.
+The following procedure creates a user-defined network that is namespace scoped. Based upon your use case, create your request by using either the `my-layer-two-udn.yaml` example for a `Layer2` topology type or the `my-layer-three-udn.yaml` example for a `Layer3` topology type.
 
 //We won't have these pieces till GA in 4.18.
 //[NOTE]

modules/nw-udn-cr.adoc

@@ -9,16 +9,20 @@ 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 (UDNs) in the default the OVN-Kubernetes CNI plugin for {product-title}, the Kubernetes Layer 3 topology was supported as the primary network, or _main_ network, to where all pods attach. The Kubernetes design principle requires that all pods communicate with each other by their IP addresses, and Kubernetes restricts inter-pod traffic according to the Kubernetes network policy. While the Kubernetes design is useful for simple deployments, the Layer 3 topology restricts customization of primary network segment configurations, especially for modern multi-tenant deployments.
 
-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. You can build a UDN by using a Virtual Router Function (VRF).
+
+The following diagram shows four cluster namespaces, where each namespace has a single assigned 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 the Kubernetes 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.
+
+image::527-OpenShift-UDN-isolation-012025.png[Namespace isolation concept in a user-defined network (UDN)]
 
 [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}.
 ====
 
-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. 
+Unlike a network attachment definition (NAD), which is only namespaced scope, 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 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.
 
@@ -31,7 +35,7 @@ The following sections further emphasize the benefits and limitations of user-de
 //** EgressQoS
 //** EgressService
 //** EgressIP
-//** Load balancer and NodePort services, as well as services with external IPs.
+//** Load balancer and NodePort services, and services with external IPs.
 
 //benefits of UDN
 include::modules/nw-udn-benefits.adoc[leveloffset=+1]