Update the SDN migration procedure for release 4.8

- https://issues.redhat.com/browse/OSDOCS-1809

Author: jboxman

modules/nw-ovn-kubernetes-migration-about.adoc

@@ -7,7 +7,7 @@
 
 Migrating to the OVN-Kubernetes Container Network Interface (CNI) cluster network provider is a manual process that includes some downtime during which your cluster is unreachable. Although a rollback procedure is provided, the migration is intended to be a one-way process.
 
-A migration to the OVN-Kubernetes cluster network provider is supported on installer-provisioned clusters on the following platforms:
+A migration to the OVN-Kubernetes cluster network provider is supported on the following platforms:
 
 * Bare metal hardware
 * Amazon Web Services (AWS)
@@ -16,11 +16,6 @@ A migration to the OVN-Kubernetes cluster network provider is supported on insta
 * {rh-openstack-first}
 * VMware vSphere
 
-[NOTE]
-====
-Performing a migration on a user-provisioned cluster is not supported.
-====
-
 [id="considerations-migrating-ovn-kubernetes-network-provider_{context}"]
 == Considerations for migrating to the OVN-Kubernetes network provider
 
@@ -130,14 +125,71 @@ OVN-Kubernetes fully supports the Kubernetes `NetworkPolicy` API in the `network
 [id="how-the-migration-process-works_{context}"]
 == How the migration process works
 
-The migration process works as follows:
+The following table summarizes the migration process by segmenting between the user-initiated steps in the process and the actions that the migration performs in response.
+
+.Migrating to OVN-Kubernetes from OpenShift SDN
+[cols="1,1a",options="header"]
+|===
+
+|User-initiated steps|Migration activity
+
+|
+Set the `migration` field of the `Network.operator.openshift.io` custom resource (CR) named `cluster` to `OVNKubernetes`. Make sure the `migration` field is `null` before setting it to a value.
+|
+Cluster Network Operator (CNO):: Updates the status of the `Network.config.openshift.io` CR named `cluster` accordingly.
+Machine Config Operator (MCO):: Rolls out an update to the systemd configuration necessary for OVN-Kubernetes; The MCO updates a single machine per pool at a time by default, causing the total time the migration takes to increase with the size of the cluster.
+
+|Update the `networkType` field of the `Network.config.openshift.io` CR.
+|
+CNO:: Performs the following actions:
++
+--
+* Destroys the OpenShift SDN control plane pods.
+* Deploys the OVN-Kubernetes control plane pods.
+* Updates the Multus objects to reflect the new cluster network provider.
+--
 
-. Set a temporary annotation set on the Cluster Network Operator (CNO) configuration object. This annotation triggers the CNO to watch for a change to the `defaultNetwork` field.
+|
+Reboot each node in the cluster.
+|
+Cluster:: As nodes reboot, the cluster assigns IP addresses to pods on the OVN-Kubernetes cluster network.
 
-. Suspend the Machine Config Operator (MCO) to ensure that it does not interrupt the migration.
+|===
 
-. Update the `defaultNetwork` field. The update causes the CNO to destroy the OpenShift SDN control plane pods and deploy the OVN-Kubernetes control plane pods. Additionally, it updates the Multus objects to reflect the new cluster network provider.
+If a rollback to OpenShift SDN is required, the following table describes the process.
 
-. Reboot each node in the cluster. Because the existing pods in the cluster are unaware of the change to the cluster network provider, rebooting each node ensures that each node is drained of pods. New pods are attached to the new cluster network provided by OVN-Kubernetes.
+.Performing a rollback to OpenShift SDN
+[cols="1,1a",options="header"]
+|===
 
-. Enable the MCO after all nodes in the cluster reboot. The MCO rolls out an update to the systemd configuration necessary to complete the migration. The MCO updates a single machine per pool at a time by default, so the total time the migration takes increases with the size of the cluster.
+|User-initiated steps|Migration activity
+
+|Suspend the MCO to ensure that it does not interrupt the migration.
+|The MCO stops.
+
+|
+Set the `migration` field of the `Network.operator.openshift.io` custom resource (CR) named `cluster` to `OVNKubernetes`. Make sure the `migration` field is `null` before setting it to a value.
+|
+CNO:: Updates the status of the `Network.config.openshift.io` CR named `cluster` accordingly.
+
+|Update the `networkType` field.
+|
+CNO:: Performs the following actions:
++
+--
+* Destroys the OpenShift SDN control plane pods.
+* Deploys the OVN-Kubernetes control plane pods.
+* Updates the Multus objects to reflect the new cluster network provider.
+--
+
+|
+Reboot each node in the cluster.
+|
+Cluster:: As nodes reboot, the cluster assigns IP addresses to pods on the OVN-Kubernetes cluster network.
+
+|
+Enable the MCO after all nodes in the cluster reboot.
+|
+MCO:: Rolls out an update to the systemd configuration necessary for OpenShift SDN; The MCO updates a single machine per pool at a time by default, so the total time the migration takes increases with the size of the cluster.
+
+|===