MIG-717: Update intro for OCP3>4 guide

Author: apinnick

migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc

@@ -5,14 +5,31 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-{product-title} 4 includes new technologies and functionality that results in a cluster that is self-managing, flexible, and automated. The way that {product-title} 4 clusters are deployed and managed drastically differs from {product-title} 3.
+{product-title} 4 contains new technologies and functionality that result in a cluster that is self-managing, flexible, and automated. {product-title} 4 clusters are deployed and managed very differently from {product-title} 3.
 
-To successfully transition from {product-title} 3 to {product-title} 4, it is important that you review the following information:
+The most effective way to migrate from {product-title} 3 to 4 is by using a CI/CD pipeline to automate deployments in an link:https://www.redhat.com/en/topics/devops/what-is-application-lifecycle-management-alm[application lifecycle management] framework.
+
+If you do not have a CI/CD pipeline or if you are migrating stateful applications, you can use the {mtc-full} ({mtc-short}) to migrate your application workloads.
+
+To successfully transition to {product-title} 4, review the following information:
 
 xref:../migrating_from_ocp_3_to_4/planning-migration-3-4.adoc#planning-migration-3-4[Differences between {product-title} 3 and 4]::
-Learn about the differences between {product-title} versions 3 and 4. Prior to transitioning, be sure that you have reviewed and prepared for storage, networking, logging, security, and monitoring considerations.
+* Architecture
+* Installation and upgrade
+* Storage, network, logging, security, and monitoring considerations
 
 xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#about-mtc-3-4[About the {mtc-full}]::
-Learn about the {mtc-full} ({mtc-short}) to migrate your application workloads.
+* Workflow
+* File system and snapshot copy methods for persistent volumes (PVs)
+* Direct volume migration
+* Direct image migration
+
+xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#advanced-migration-options-3-4[Advanced migration options]::
+* Automating your migration with migration hooks
+* Using the {mtc-short} API
+* Excluding resources from a migration plan
+* Configuring the `MigrationController` custom resource for large-scale migrations
+* Enabling automatic PV resizing for direct volume migration
+* Enabling cached Kubernetes clients for improved performance
 
-For new features, enhancements, and known issues, see the xref:../migration-toolkit-for-containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
+For new features and enhancements, technical changes, and known issues, see the xref:../migration-toolkit-for-containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].

migrating_from_ocp_3_to_4/planning-migration-3-4.adoc

@@ -13,15 +13,15 @@ endif::[]
 
 It is not possible to upgrade your existing {product-title} 3 cluster to {product-title} 4. You must start with a new {product-title} 4 installation. Tools are available to assist in migrating your control plane settings and application workloads.
 
+[id="migration-differences-architecture"]
+== Architecture
+
 With {product-title} 3, administrators individually deployed {op-system-base-full} hosts, and then installed {product-title} on top of these hosts to form a cluster. Administrators were responsible for properly configuring these hosts and performing updates.
 
 {product-title} 4 represents a significant change in the way that {product-title} clusters are deployed and managed. {product-title} 4 includes new technologies and functionality, such as Operators, machine sets, and {op-system-first}, which are core to the operation of the cluster. This technology shift enables clusters to self-manage some functions previously performed by administrators. This also ensures platform stability and consistency, and simplifies installation and scaling.
 
 For more information, see xref:../architecture/architecture.adoc#architecture[OpenShift Container Platform architecture].
 
-[id="migration-differences-architecture"]
-== Architecture differences
-
 [discrete]
 === Immutable infrastructure
 
@@ -39,7 +39,7 @@ Operators are a method of packaging, deploying, and managing a Kubernetes applic
 For more information, see xref:../operators/understanding/olm-what-operators-are.adoc#olm-what-operators-are[Understanding Operators].
 
 [id="migration-differences-install"]
-== Installation and update differences
+== Installation and upgrade
 
 [discrete]
 === Installation process

migration-toolkit-for-containers/about-mtc.adoc

@@ -11,7 +11,15 @@ The {mtc-full} ({mtc-short}) enables you to migrate stateful application workloa
 
 The {mtc-short} console is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the console on a link:https://access.redhat.com/articles/5064151[remote cluster].
 
-{mtc-short} supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider.
+[id="additional-resources-_{context}"]
+[discrete]
+== Additional resources
+
+* xref:../migration-toolkit-for-containers/advanced-migration-options-mtc.adoc#advanced-migration-options-mtc[Advanced migration options]
++
+Automate your migration with migration hooks and the {mtc-short} API.
++
+Configure your migration plan to exclude resources, support large-scale migrations, and enable automatic PV resizing for direct volume migration.
 
 [id="additional-resources_{context}"]
 [discrete]

modules/migration-mtc-workflow.adoc

@@ -6,17 +6,21 @@
 [id="migration-mtc-workflow_{context}"]
 = {mtc-full} workflow
 
-You use the {mtc-full} ({mtc-short}) to migrate Kubernetes resources, persistent volume data, and internal container images from an {product-title} source cluster to an {product-title} {product-version} target cluster by using the {mtc-short} web console or the Kubernetes API.
+You use the {mtc-full} ({mtc-short}) to migrate Kubernetes resources, persistent volume data, and internal container images from to {product-title} {product-version} by using the {mtc-short} web console or the Kubernetes API.
 
-The ({mtc-short}) migrates the following resources:
+{mtc-short} migrates the following resources:
 
 * A namespace specified in a migration plan.
-
 * Namespace-scoped resources: When the {mtc-short} migrates a namespace, it migrates all the objects and resources associated with that namespace, such as services or pods. Additionally, if a resource that exists in the namespace but not at the cluster level depends on a resource that exists at the cluster level, the {mtc-short} migrates both resources.
 +
 For example, a security context constraint (SCC) is a resource that exists at the cluster level and a service account (SA) is a resource that exists at the namespace level. If an SA exists in a namespace that the {mtc-short} migrates, the {mtc-short} automatically locates any SCCs that are linked to the SA and also migrates those SCCs. Similarly, the {mtc-short} migrates persistent volume claims that are linked to the persistent volumes of the namespace.
++
+[NOTE]
+====
+Cluster-scoped resources might have to be migrated manually, depending on the resource.
+====
 
-* Custom resources (CRs) and custom resource definitions (CRDs): The {mtc-short} automatically migrates any CRs that exist at the namespace level as well as the CRDs that are linked to those CRs.
+* Custom resources (CRs) and custom resource definitions (CRDs): {mtc-short} automatically migrates CRs and CRDs at the namespace level.
 
 Migrating an application with the {mtc-short} web console involves the following steps:
 
@@ -26,7 +30,7 @@ You can install the {mtc-full} Operator in a restricted environment with limited
 
 . Configure the replication repository, an intermediate object storage that {mtc-short} uses to migrate data.
 +
-The source and target clusters must have network access to the replication repository during migration. In a restricted environment, you can use an internally hosted S3 storage repository. If you are using a proxy server, you must configure it to allow network traffic between the replication repository and the clusters.
+The source and target clusters must have network access to the replication repository during migration. In a restricted environment, you can use Multi-Cloud Object Gateway (MCG). If you are using a proxy server, you must configure it to allow network traffic between the replication repository and the clusters.
 
 . Add the source cluster to the {mtc-short} web console.
 . Add the replication repository to the {mtc-short} web console.
@@ -54,7 +58,7 @@ image::migration-PV-move.png[]
 
 * *Stage* (optional) copies data to the target cluster without stopping the application.
 +
-Staging can be run multiple times so that most of the data is copied to the target before migration. This minimizes the duration of the migration and application downtime.
+Staging can be run multiple times so that most of the data is copied to the target before migration. This minimizes the duration of the migration and the application downtime.
 
 * *Migrate* stops the application on the source cluster and recreates its resources on the target cluster. Optionally, you can migrate the workload without stopping the application.
 

modules/migration-understanding-data-copy-methods.adoc

@@ -45,8 +45,8 @@ a|* Cloud provider must support snapshots.
 * Does not support direct volume migration.
 |===
 
-[id="direct-migration_{context}"]
-== Direct volume migration and direct image migration
+[id="direct-volume-migration-and-direct-image-migration_{context}"]
+= Direct volume migration and direct image migration
 
 You can use direct image migration (DIM) and direct volume migration (DVM) to migrate images and data directly from the source cluster to the target cluster.