Merge pull request #34830 from sbeskin-redhat/BZ1968377_BPG_network_traffic_migration_strategies_added_to_MTC_docs

Bz1968377: BPG network traffic migration strategies added to MTC docs

Author: mikemckiernan

_topic_maps/_topic_map.yml

@@ -2119,7 +2119,7 @@ Topics:
 - Name: Differences between OKD 3 and 4
   File: planning-migration-3-4
   Distros: openshift-origin
-- Name: Planning considerations
+- Name: Network considerations
   File: planning-considerations-3-4
 - Name: About MTC
   File: about-mtc-3-4
@@ -2154,6 +2154,8 @@ Topics:
   File: upgrading-mtc
 - Name: Premigration checklists
   File: premigration-checklists-mtc
+- Name: Network considerations
+  File: network-considerations-mtc
 - Name: Migrating your applications
   File: migrating-applications-with-mtc
 - Name: Advanced migration options

migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc

@@ -1,16 +1,24 @@
 [id="planning-considerations-3-4"]
-= Planning considerations
+= Network considerations
 include::modules/common-attributes.adoc[]
 :context: planning-considerations-3-4
 
 toc::[]
 
-This section describes considerations and strategies for planning your migration from {product-title} 3 to 4.
+Review the strategies for redirecting your application network traffic after migration.
 
-include::modules/migration-DNS-considerations.adoc[leveloffset=+1]
-include::modules/migration-isolating-dns-domain-of-target-cluster-from-clients.adoc[leveloffset=+1]
-include::modules/migration-setting-up-target-cluster-to-accept-source-dns-domain.adoc[leveloffset=+1]
+[id="dns-considerations_{context}"]
+== DNS considerations
+
+The DNS domain of the target cluster is different from the domain of the source cluster. By default, applications get FQDNs of the target cluster after migration.
+
+To preserve the source DNS domain of migrated applications, select one of the two options described below.
+
+include::modules/migration-isolating-dns-domain-of-target-cluster-from-clients.adoc[leveloffset=+2]
+include::modules/migration-setting-up-target-cluster-to-accept-source-dns-domain.adoc[leveloffset=+2]
 
 .Additional resources
 
 * See xref:../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing the default ingress certificate] for more information.
+
+include::modules/migration-network-traffic-redirection-strategies.adoc[leveloffset=+1]

migration_toolkit_for_containers/network-considerations-mtc.adoc

@@ -0,0 +1,24 @@
+[id="network-considerations-mtc"]
+= Network considerations
+include::modules/common-attributes.adoc[]
+:context: network-considerations-mtc
+
+toc::[]
+
+Review the strategies for redirecting your application network traffic after migration.
+
+[id="dns-considerations_{context}"]
+== DNS considerations
+
+The DNS domain of the target cluster is different from the domain of the source cluster. By default, applications get FQDNs of the target cluster after migration.
+
+To preserve the source DNS domain of migrated applications, select one of the two options described below.
+
+include::modules/migration-isolating-dns-domain-of-target-cluster-from-clients.adoc[leveloffset=+2]
+include::modules/migration-setting-up-target-cluster-to-accept-source-dns-domain.adoc[leveloffset=+2]
+
+.Additional resources
+
+* See xref:../security/certificates/replacing-default-ingress-certificate.adoc#replacing-default-ingress[Replacing the default ingress certificate] for more information.
+
+include::modules/migration-network-traffic-redirection-strategies.adoc[leveloffset=+1]

modules/migration-DNS-considerations.adoc

@@ -1,26 +1,28 @@
 // Module included in the following assemblies:
 //
 // * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+// * migration_toolkit_for_containers/network-considerations-mtc.adoc
 
-[id="isolating-dns-domain-of-target-cluster-from-clients_{context}"]
-== Isolating the DNS domain of the target cluster from the clients
+[id="migration-isolating-dns-domain-of-target-cluster-from-clients_{context}"]
+= Isolating the DNS domain of the target cluster from the clients
 
 You can allow the clients' requests sent to the DNS domain of the source cluster to reach the DNS domain of the target cluster without exposing the target cluster to the clients.
 
 .Procedure
-. Place an exterior network component, such as an application load balancer or a reverse proxy, between the clients and the OpenShift Container Platform 4 cluster.
 
-. Update the original application FQDN (`app1.apps.ocp3.example.com`) in the DNS server to return the IP address of the exterior network component.
+. Place an exterior network component, such as an application load balancer or a reverse proxy, between the clients and the target cluster.
 
-. Configure the network component to send requests received for the application in the source domain to the load balancer in the target {product-title} 4 cluster domain.
+. Update the application FQDN on the source cluster in the DNS server to return the IP address of the exterior network component.
 
-. Create a wildcard DNS record for the `*.apps.ocp3.example.com` domain that points to the IP address of the load balancer of the source cluster.
+. Configure the network component to send requests received for the application in the source domain to the load balancer in the target cluster domain.
 
-. Create a specific DNS record for each application that points to the IP address of the exterior network component in front of the target cluster. A specific DNS record has higher priority than a wildcard record, so no conflict arises when the application FQDN is resolved.
+. Create a wildcard DNS record for the `*.apps.source.example.com` domain that points to the IP address of the load balancer of the source cluster.
+
+. Create a DNS record for each application that points to the IP address of the exterior network component in front of the target cluster. A specific DNS record has higher priority than a wildcard record, so no conflict arises when the application FQDN is resolved.
 
 [NOTE]
 ====
-* The exterior network component must terminate all secure TLS connections. If the connections pass through to the {product-title} 4 load balancer, the FQDN of the target application is exposed to the client and certificate errors occur.
+* The exterior network component must terminate all secure TLS connections. If the connections pass through to the target cluster load balancer, the FQDN of the target application is exposed to the client and certificate errors occur.
 
 * The applications must not return links referencing the target cluster domain to the clients. Otherwise, parts of the application might not load or work properly.
 ====

modules/migration-isolating-dns-domain-of-target-cluster-from-clients.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+// * migration_toolkit_for_containers/network-considerations-mtc.adoc
+
+[id="migration-network-traffic-redirection-strategies_{context}"]
+= Network traffic redirection strategies
+
+After a successful migration, you must redirect network traffic of your stateless applications from the source cluster to the target cluster.
+
+The strategies for redirecting network traffic are based on the following assumptions:
+
+* The application pods are running on both the source and target clusters.
+* Each application has a route that contains the source cluster hostname.
+* The route with the source cluster hostname contains a CA certificate.
+* For HTTPS, the target router CA certificate contains a Subject Alternative Name for the wildcard DNS record of the source cluster.
+
+Consider the following strategies and select the one that meets your objectives.
+
+* Redirecting all network traffic for all applications at the same time
++
+Change the wildcard DNS record of the source cluster to point to the target cluster router's virtual IP address (VIP).
++
+This strategy is suitable for simple applications or small migrations.
+
+* Redirecting network traffic for individual applications
++
+Create a DNS record for each application with the source cluster hostname pointing to the target cluster router's VIP. This DNS record takes precedence over the source cluster wildcard DNS record.
+
+* Redirecting network traffic gradually for individual applications
+
+. Create a proxy that can direct traffic to both the source cluster router's VIP and the target cluster router's VIP, for each application.
+. Create a DNS record for each application with the source cluster hostname pointing to the proxy.
+. Configure the proxy entry for the application to route a percentage of the traffic to the target cluster router's VIP and the rest of the traffic to the source cluster router's VIP.
+. Gradually increase the percentage of traffic that you route to the target cluster router's VIP until all the network traffic is redirected.
+
+* User-based redirection of traffic for individual applications
++
+Using this strategy, you can filter TCP/IP headers of user requests to redirect network traffic for predefined groups of users. This allows you to test the redirection process on specific populations of users before redirecting the entire network traffic.
+
+. Create a proxy that can direct traffic to both the source cluster router's VIP and the target cluster router's VIP, for each application.
+. Create a DNS record for each application with the source cluster hostname pointing to the proxy.
+. Configure the proxy entry for the application to route traffic matching a given header pattern, such as `test customers`, to the target cluster router's VIP and the rest of the traffic to the source cluster router's VIP.
+. Redirect traffic to the target cluster router's VIP in stages until all the traffic is on the target cluster router's VIP.

modules/migration-network-traffic-redirection-strategies.adoc

@@ -1,34 +1,35 @@
 // Module included in the following assemblies:
 //
 // * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+// * migration_toolkit_for_containers/network-considerations-mtc.adoc
 
-[id="setting-up-target-cluster-to-accept-source-dns-domain_{context}"]
-== Setting up the target cluster to accept the source DNS domain
+[id="migration-setting-up-target-cluster-to-accept-source-dns-domain_{context}"]
+= Setting up the target cluster to accept the source DNS domain
 
-You can set up the target cluster to accept requests for migrated applications in the DNS domain of the source cluster.
+You can set up the target cluster to accept requests for a migrated application in the DNS domain of the source cluster.
 
 .Procedure
 
 For both non-secure HTTP access and secure HTTPS access, perform the following steps:
 
-. Create a route in the application’s project for the hostname that applications used in the source cluster:
+. Create a route in the target cluster's project that is configured to accept requests addressed to the application's FQDN in the source cluster:
 +
 [source,terminal]
 ----
-$ oc expose svc app1-svc --hostname app1.apps.ocp3.example.com \
- -n app1-namespace
+$ oc expose svc <app1-svc> --hostname <app1.apps.source.example.com> \
+ -n <app1-namespace>
 ----
 +
 With this new route in place, the server accepts any request for that FQDN and sends it to the corresponding application pods.
-In addition, when you migrate the application, another route is created in the target cluster domain (`app1.apps.ocp4.example.com`). Requests can reach the migrated application using both of these hostnames.
+In addition, when you migrate the application, another route is created in the target cluster domain. Requests reach the migrated application using either of these hostnames.
 
-. Create a specific DNS record for the FQDN in the route hostname parameter that points to the IP address of the default load balancer of the target cluster. Specific DNS records take priority over wildcard records.
+. Create a DNS record with your DNS provider that points the application's FQDN in the source cluster to the IP address of the default load balancer of the target cluster. This will redirect traffic away from your source cluster to your target cluster.
 +
 The FQDN of the application resolves to the load balancer of the target cluster. The default ingress controller router accept requests for that FQDN because a route for that hostname is exposed.
 
 For secure HTTPS access, perform the following additional step:
 
 . Replace the x509 certificate of the default ingress controller created during the installation process with a custom certificate.
 . Configure this certificate to include the wildcard DNS domains for both the source and target clusters in the `subjectAltName` field.
-+ 
-The new certificate is valid for securing connections made using either of the two DNS domains.
++
+The new certificate is valid for securing connections made using either DNS domain.