Merge pull request #91435 from dfitzmau/DIAGRAMS-504-17

DIAGRAMS-504: Layer 2 UDN diagram

Author: dfitzmau

images/504_OpenShift_UDN_L2_0325.png

@@ -33,6 +33,3 @@ Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider t
 
 * The cluster subnet and services CIDR for a UDN cannot overlap with the default cluster subnet CIDR. OVN-Kubernetes network plugin uses `100.64.0.0/16` as the default join subnet for the network, you must not use that value to configure a UDN `joinSubnets` field. If the default address values are used anywhere in the network for the cluster you must override the default values by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
 
-* A layer 2 topology creates a virtual switch that is distributed across all nodes in a cluster. Virtual machines and pods connect to this virtual switch so that all these components can communicate with each other within the same subnet. If you decide not to specify a layer 2 subnet, then you must manually configure IP addresses for each pod in your cluster. When not specifying a layer 2 subnet, port security is limited to preventing Media Access Control (MAC) spoofing only, and does not include IP spoofing. A layer 2 topology creates a single broadcast domain that can be challenging in large network environments, whereby the topology might cause a broadcast storm that can degrade network performance. 
-
-* A layer 3 topology creates a unique layer 2 segment for each node in a cluster. The layer 3 routing mechanism interconnects these segments so that virtual machines and pods that are hosted on different nodes can communicate with each other. A layer 3 topology can effectively manage large broadcast domains by assigning each domain to a specific node, so that broadcast traffic has a reduced scope. To configure a layer 3 topology, you must configure `cidr` and `hostSubnet` parameters.

modules/nw-udn-best-practices.adoc

@@ -0,0 +1,20 @@
+//module included in the following assembly:
+//
+// *networking/multiple_networks/about-user-defined-networks.adoc
+:_mod-docs-content-type: REFERENCE
+[id="nw-udn-l2-l3_{context}"]
+= Layer 2 and layer 3 topologies
+
+A layer 2 topology creates a virtual switch that is distributed across all nodes in a cluster. Virtual machines and pods connect to this virtual switch so that all these components can communicate with each other within the same subnet. If you decide not to specify a layer 2 subnet, then you must manually configure IP addresses for each pod in your cluster. When you do not specify a layer 2 subnet, port security is limited to preventing Media Access Control (MAC) spoofing only, and does not include IP spoofing. A layer 2 topology creates a single broadcast domain that can be challenging in large network environments, where the topology might cause a broadcast storm that can degrade network performance. 
+
+The following diagram shows two nodes that use an UDN with a layer 2 topology to live migrate a pod from `Node 1` to `Node 2`. Each node includes two interfaces:
+
+* A node interface, which is a compute node that connects networking components to the node.
+* An Open vSwitch (OVS) bridge such as `br-ex`, which creates an layer 2 OVN switch so that pods can communicate with each other and share resources. 
+
+An external switch connects these two interfaces, while the gateway or router handles routing traffic between the external switch and the layer 2 OVN switch. Pods in a node can use the UDN to communicate with each other. The layer 2 OVN switch handles node traffic over UDN so that live migrate of a pod from one node to another is possible. 
+
+.A user-defined network (UDN) that uses a layer 2 topology
+image::504_OpenShift_UDN_L2_0325.png[A UDN that uses a layer 2 topology for migrating a pod from node-1 to node-2]
+
+A layer 3 topology creates a unique layer 2 segment for each node in a cluster. The layer 3 routing mechanism interconnects these segments so that virtual machines and pods that are hosted on different nodes can communicate with each other. A layer 3 topology can effectively manage large broadcast domains by assigning each domain to a specific node, so that broadcast traffic has a reduced scope. To configure a layer 3 topology, you must configure `cidr` and `hostSubnet` parameters.

modules/nw-udn-l2-l3.adoc

@@ -20,4 +20,4 @@ While user-defined networks (UDN) offer highly customizable network configuratio
 
 * *Health check limitations*: Kubelet health checks are performed by the cluster default network, which does not confirm the network connectivity of the primary interface on the pod. Consequently, scenarios where a pod appears healthy by the default network, but has broken connectivity on the primary interface, are possible with user-defined networks.
 
-* *Network policy limitations*: Network policies that enable traffic between namespaces connected to different user-defined primary networks are not effective. These traffic policies do not take effect because there is no connectivity between these isolated networks.
+* *Network policy limitations*: Network policies that enable traffic between namespaces connected to different user-defined primary networks are not effective. These traffic policies do not take effect because there is no connectivity between these isolated networks.

modules/nw-udn-limitations.adoc

@@ -50,6 +50,9 @@ include::modules/nw-udn-benefits.adoc[leveloffset=+1]
 //Limitations that users should consider for UDN.
 include::modules/nw-udn-limitations.adoc[leveloffset=+1]
 
+// Layer 2 and layer 3 topologies
+include::modules/nw-udn-l2-l3.adoc[leveloffset=+1]
+
 //Best practices for using UDN.
 include::modules/nw-udn-best-practices.adoc[leveloffset=+1]