Merge pull request #88865 from dfitzmau/OCPBUGS-48271-17

[enterprise-4.17] OCPBUGS-48271: Updated UDN doc to expand on Layer 2 and 3

Author: dfitzmau

modules/nw-udn-best-practices.adoc

@@ -29,5 +29,10 @@ Before setting up a `UserDefinedNetwork` (UDN) resource, users should consider t
 
 * When creating network segmentation, you should only use the NAD resource if user-defined network segmentation cannot be completed using the UDN resource.
 
-* 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 network's join subnet, you must not use that value to configure a UDN `joinSubnets` field. If the default address values are used anywhere in the cluster's network you must override it by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
+* 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 network's join subnet, 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 it by setting the `joinSubnets` field. For more information, see "Additional configuration details for a UserDefinedNetworks CR".
 
+* 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-cr.adoc

@@ -65,6 +65,7 @@ spec:
         hostSubnet: 24
       - cidr: 2001:db8::/60
         hostSubnet: 64
+# ...
 ----
 <1> Name of your `UserDefinedNetwork` resource. This should not be `default` or duplicate any global namespaces created by the Cluster Network Operator (CNO).
 <2> The `topology` field describes the network configuration; accepted values are `Layer2` and `Layer3`. Specifying a `Layer3` topology type creates a layer 2 segment per node, each with a different subnet. Layer 3 routing is used to interconnect node subnets.
@@ -74,8 +75,8 @@ spec:
 +
 * The `subnets` field is mandatory.
 * The type for the `subnets` field is `cidr` and `hostSubnet`:
-** `cidr` is the cluster subnet and accepts a string value.
-** `hostSubnet` specifies the nodes subnet prefix that the cluster subnet is split to.
+** `cidr` is equivalent to the `clusterNetwork` configuration settings of a cluster. The IP addresses in the CIDR are distributed to pods in the user defined network. This parameter accepts a string value.
+** `hostSubnet` defines the per-node subnet prefix.
 ** For IPv6, only a `/64` length is supported for `hostSubnet`.
 +
 . Apply your request by running the following command: