Update OVN-Kubernetes migration procedure

- https://issues.redhat.com/browse/OSDOCS-1524
- https://bugzilla.redhat.com/show_bug.cgi?id=1854306

Co-authored-by: Kathryn Alexander <[email protected]>

Author: jboxman

_topic_map.yml

@@ -721,9 +721,9 @@ Topics:
   Topics:
   - Name: About the OVN-Kubernetes network provider
     File: about-ovn-kubernetes
-  - Name: Migrate from the OpenShift SDN default CNI network provider
+  - Name: Migrate from the OpenShift SDN cluster network provider
     File: migrate-from-openshift-sdn
-  - Name: Rollback to the OpenShift SDN default CNI network provider
+  - Name: Rollback to the OpenShift SDN cluster network provider
     File: rollback-to-openshift-sdn
   - Name: Configuring an egress firewall for a project
     File: configuring-egress-firewall-ovn

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

@@ -0,0 +1,133 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/migrate-from-openshift-sdn.adoc
+
+[id="nw-ovn-kubernetes-migration-about_{context}"]
+= Migration to the OVN-Kubernetes network provider
+
+Migrating to the OVN-Kubernetes Container Network Interface (CNI) default 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.
+
+[NOTE]
+====
+A migration to the OVN-Kubernetes network provider is supported on installer-provisioned clusters on only bare metal hardware.
+
+Performing a migration on a user-provisioned cluster on bare metal hardware is not supported.
+====
+
+[id="considerations-migrating-ovn-kubernetes-network-provider_{context}"]
+== Considerations for migrating to the OVN-Kubernetes network provider
+
+The subnets assigned to nodes and the IP addresses assigned to individual pods are not preserved during the migration.
+
+While the OVN-Kubernetes network provider implements many of the capabilities present in the OpenShift SDN network provider, the configuration is not the same.
+
+If your cluster uses any of the following OpenShift SDN capabilities, you must manually configure the same capability in OVN-Kubernetes:
+
+* Namespace isolation
+* Egress IP addresses
+* Egress network policies
+* Egress router pods
+* Multicast
+* Network policies
+
+The following sections highlight the differences in configuration between the aforementioned capabilities in OVN-Kubernetes and OpenShift SDN.
+
+[id="how-the-migration-process-works_{context}"]
+== How the migration process works
+
+The migration process works as follows:
+
+. 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.
+
+. 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.
+
+. 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.
+
+. 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.
+
+[discrete]
+[id="namespace-isolation_{context}"]
+=== Namespace isolation
+
+OVN-Kubernetes supports only the network policy isolation mode.
+
+[IMPORTANT]
+====
+If your cluster is using OpenShift SDN configured in either the multitenant or subnet isolation modes, you cannot migrate to the OVN-Kubernetes network provider.
+====
+
+[discrete]
+[id="egress-ip-addresses_{context}"]
+=== Egress IP addresses
+
+The differences in configuring an egress IP address between OVN-Kubernetes and OpenShift SDN is described in the following table:
+
+.Differences in egress IP address configuration
+[cols="1a,1a",options="header"]
+|===
+|OVN-Kubernetes|OpenShift SDN
+
+|
+* Create an `EgressIPs` object
+* Add an annotation on a `Node` object
+
+|
+* Patch a `NetNamespace` object
+* Patch a `HostSubnet` object
+|===
+
+For more information on using egress IP addresses in OVN-Kubernetes, see "Configuring an egress IP address".
+
+[discrete]
+[id="egress-network-policies_{context}"]
+=== Egress network policies
+
+The difference in configuring an egress network policy, also known as an egress firewall, between OVN-Kubernetes and OpenShift SDN is described in the following table:
+
+.Differences in egress network policy configuration
+[cols="1a,1a",options="header"]
+|===
+|OVN-Kubernetes|OpenShift SDN
+
+|
+* Create an `EgressFirewall` object in a namespace
+
+|
+* Create an `EgressNetworkPolicy` object in a namespace
+|===
+
+For more information on using an egress firewall in OVN-Kubernetes, see "Configuring an egress firewall for a project".
+
+[discrete]
+[id="egress-router-pods_{context}"]
+=== Egress router pods
+
+OVN-Kubernetes does not support using egress router pods in {product-title} 4.6.
+
+[discrete]
+[id="multicast_{context}"]
+=== Multicast
+
+The difference between enabling multicast traffic on OVN-Kubernetes and OpenShift SDN is described in the following table:
+
+.Differences in multicast configuration
+[cols="1a,1a",options="header"]
+|===
+|OVN-Kubernetes|OpenShift SDN
+
+|
+* Add an annotation on a `Namespace` object
+
+|
+* Add an annotation on a `NetNamespace` object
+|===
+
+For more information on using an egress firewall in OVN-Kubernetes, see "Enabling multicast for a project".
+
+[discrete]
+[id="network-policies_{context}"]
+=== Network policies
+
+OVN-Kubernetes fully supports the Kubernetes `NetworkPolicy` API in the `networking.k8s.io/v1` API group. No changes are necessary in your network policies when migrating from OpenShift SDN.