OSDOCS-5269: add network topology diagram

Author: ShaunaDiaz

images/317_RHbM_OVN_topology_0323.png

@@ -18,7 +18,7 @@ By default, Kubernetes allocates each pod an internal IP address for application
 
 [NOTE]
 ====
-To troubleshoot NodePort connection problems, read about the known issue in the Release Notes.
+To troubleshoot connection problems with the NodePort service, read about the known issue in the Release Notes.
 ====
 
 include::modules/microshift-cni.adoc[leveloffset=+1]

microshift_networking/microshift-networking.adoc

@@ -10,12 +10,48 @@ OVN-Kubernetes is the default networking solution for {product-title} deployment
 
 [id="microshift-network-topology_{context}"]
 == Network topology
-OVN-Kubernetes provides an overlay-based networking implementation. This overlay includes an OVS-based implementation of Service and NetworkPolicy. The overlay network uses the geneve tunnel, so the pod maximum transmission unit (MTU) is set to smaller than that of the physical interface on the host to remove the tunnel header.
+OVN-Kubernetes provides an overlay-based networking implementation. This overlay includes an OVS-based implementation of Service and NetworkPolicy. The overlay network uses the Geneve (Generic Network Virtualization Encapsulation) tunnel protocol. The pod maximum transmission unit (MTU) for the Geneve tunnel is set to a smaller value than the MTU of the physical interface on the host. This smaller MTU makes room for the required information that is added to the tunnel header before it is transmitted.
 
 OVS runs as a systemd service on the {product-title} node. The OVS RPM package is installed as a dependency to the `microshift-networking` RPM package. OVS is started immediately when the `microshift-networking` RPM is installed.
 
+.{product-title} network topology
+image:317_RHbM_OVN_topology_0323.png[title="{product-title} uses an overlay-based networking implementation, details follow."]
+
+[id="microshift-description-ovn-logical-components_{context}"]
+=== Description of the OVN logical components of the virtualized network
+OVN node switch::
+A virtual switch named `<node-name>`. The OVN node switch is named according to the hostname of the node.
+** In this example, the `node-name` is `microshift-dev`.
+
+OVN cluster router::
+A virtual router named `ovn_cluster_router`, also known as the distributed router.
+** In this example, the cluster network is `10.42.0.0/16`.
+
+OVN join switch::
+A virtual switch named `join`.
+
+OVN gateway router::
+A virtual router named `GR_<node-name>`, also known as the external gateway router.
+
+OVN external switch::
+A virtual switch named `ext_<node-name>.`
+
+[id="microshift-description-connections-network-topology_{context}"]
+=== Description of the connections in the network topology figure
+* The north-south traffic between the network service device `enp1s0` and the OVN external switch `ext_microshift-dev`, is provided through the OVS patch port by the gateway bridge `br-ex`.
+* The OVN gateway router `GR_microshift-dev` is connected to the external network switch `ext_microshift-dev` through the logical router port 4. Port 4 is attached with the node IP address 192.168.122.14.
+* The join switch `join` connects the OVN gateway router `GR_microshift-dev` to the OVN cluster router `ovn_cluster_router`. The IP address range is 100.62.0.0/16.
+** The OVN gateway router `GR_microshift-dev` connects to the OVN join switch `join` through the logical router port 3. Port 3 attaches with the internal IP address 100.64.0.2.
+** The OVN cluster router `ovn_cluster_router` connects to the join switch `join` through the logical router port 2. Port 2 attaches with the internal IP address 100.64.0.1.
+* The OVN cluster router `ovn_cluster_router` connects to the node switch `microshift-dev` through the logical router port 1. Port 1 is attached with the OVN cluster network IP address 10.42.0.1.
+* The east-west traffic between the pods and the network service is provided by the OVN cluster router `ovn_cluster_router` and the node switch `microshift-dev`. The IP address range is 10.42.0.0/24.
+* The east-west traffic between pods is provided by the node switch `microshift-dev` without network address translation (NAT).
+* The north-south traffic between the pods and the external network is provided by the OVN cluster router `ovn_cluster_router` and the host network. This router is connected through the `ovn-kubernetes` management port `ovn-k8s-mp0`, with the IP address 10.42.0.2.
+* All the pods are connected to the OVN node switch through their interfaces.
+** In this example, Pod 1 and Pod 2 are connected to the node switch through `Interface 1` and `Interface 2`.
+
 [id="microshift-ip-forward_{context}"]
-=== IP forward
+== IP forward
 The host network `sysctl net.ipv4.ip_forward` kernel parameter is automatically enabled by the `ovnkube-master` container when started. This is required to forward incoming traffic to the CNI. For example, accessing the NodePort service from outside of a cluster fails if `ip_forward` is disabled.
 
 [id="microshift-network-performance_{context}"]
@@ -43,8 +79,6 @@ Networking features not available with {product-title} {product-version}:
 * IPsec: not supported
 * Hardware offload: not supported
 
-//watch USHIFT-640 for updates to architectural docs that will clarify features
-
 //Q: are there immutable network settings we should tell users about?
 [id="microshift-network-comps-svcs_{context}"]
 == {product-title} networking components and services
@@ -92,17 +126,13 @@ You can set up one additional host interface for cluster ingress and egress in t
 Either two or three OVS bridges are created based on the CNI configuration:
 
 Default deployment::
-* The `externalGatewayInterface` in not specified in the `ovn.yaml` config file.
+* The `externalGatewayInterface` is not specified in the `ovn.yaml` config file.
 * Two OVS bridges, `br-ex` and `br-int`, are created.
 
 Customized deployment::
 * The `externalGatewayInterface` is user-specified in the `ovn.yaml` config file.
 * Three OVS bridges are created: `br-ex`, `br-ex1` and `br-int`.
 
-//Q: We need to include the third bridge if we want to include this level of detail.
 The br-ex bridge is created by `microshift-ovs-init.service` or manually. The br-ex bridge contains statically programmed openflow rules which distinguish traffic to and from the host network (underlay) and the OVN network (overlay).
 
 The `br-int` bridge is created by the `ovnkube-master` container. The `br-int` bridge contains dynamically programmed openflow rules which handle cluster network traffic.
-
-//The `br-ex1` bridge is created by...
-//Q: need details.