Merge pull request #34834 from sbeskin-redhat/BZ1968352_BPG_DNS_considerations_added_to_MTC_docs

Author: Bob Furu

_topic_map.yml

@@ -2157,8 +2157,8 @@ Topics:
 - Name: Differences between OKD 3 and 4
   File: planning-migration-3-4
   Distros: openshift-origin
-# - Name: Planning considerations
-#   File: planning-considerations-3-4
+- Name: Planning considerations
+  File: planning-considerations-3-4
 - Name: About MTC
   File: about-mtc-3-4
 - Name: Installing MTC

migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc

@@ -7,6 +7,10 @@ toc::[]
 
 This section describes considerations and strategies for planning your migration from {product-title} 3 to 4.
 
-// content:
-// https://bugzilla.redhat.com/show_bug.cgi?id=1968377
-// https://bugzilla.redhat.com/show_bug.cgi?id=1968352
+include::modules/migration-DNS-considerations.adoc[leveloffset=+2]
+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.

modules/migration-DNS-considerations.adoc

@@ -0,0 +1,10 @@
+// Module included in the following assemblies:
+//
+// * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+
+[id="migration-dns-considerations_{context}"]
+= DNS considerations
+
+The DNS domain of the {product-title} 4 target cluster is different from the domain of the {product-title} 3 source cluster. By default, applications get FQDNs of the {product-title} 4 cluster after migration.
+
+To preserve the source DNS domain of migrated applications, select one of the two options described below.

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

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+
+[id="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.
+
+. 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.
+
+. 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.
+
+. 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.
+
+[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 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-setting-up-target-cluster-to-accept-source-dns-domain.adoc

@@ -0,0 +1,34 @@
+// Module included in the following assemblies:
+//
+// * migrating_from_ocp_3_to_4/planning-considerations-3-4.adoc
+
+[id="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.
+
+.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:
++
+[source,terminal]
+----
+$ oc expose svc app1-svc --hostname app1.apps.ocp3.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.
+
+. 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.
++
+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.