DIAGRAMS-504: Layer 2 UDN diagram

Author: dfitzmau

images/504_OpenShift_UDN_L2_0325.png

@@ -43,6 +43,3 @@ Before setting up a `UserDefinedNetwork` custom resource (CR), you should consid
 
 * The cluster subnet and services CIDR for a `UserDefinedNetwork` CR 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 `UserDefinedNetwork` CR's `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 user-defined networks".
 
-* 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

@@ -27,6 +27,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]
+
 //About CUDN CR
 include::modules/nw-cudn-about.adoc[leveloffset=+1]