BZ1959400: Break out OCP 3 to 4 migration into top level doc

Author: apinnick

_topic_map.yml

@@ -1938,27 +1938,31 @@ Topics:
   - Name: Recovering from expired control plane certificates
     File: scenario-3-expired-certs
 ---
+Name: Migrating from OpenShift Container Platform 3 to 4
+Dir: migrating_from_ocp_3_to_4
+Distros: openshift-enterprise,openshift-origin
+Topics:
+- Name: About migrating from OpenShift Container Platform 3 to 4
+  File: about-migrating-from-3-to-4
+- Name: Planning your migration
+  File: planning-migration-3-4
+- Name: About the Migration Toolkit for Containers
+  File: about-mtc-3-4
+- Name: Installing MTC
+  File: installing-3-4
+- Name: Installing MTC in a restricted network environment
+  File: installing-restricted-3-4
+- Name: Upgrading MTC
+  File: upgrading-3-4
+- Name: Migrating your applications
+  File: migrating-applications-3-4
+- Name: Troubleshooting
+  File: troubleshooting-3-4
+---
 Name: Migration Toolkit for Containers
 Dir: migration
 Distros: openshift-enterprise,openshift-origin
 Topics:
-- Name: Migrating from OpenShift Container Platform 3
-  Dir: migrating_3_4
-  Topics:
-  - Name: About migrating from OpenShift Container Platform 3 to 4
-    File: about-migration
-  - Name: Planning your migration from OpenShift Container Platform 3 to 4
-    File: planning-migration-3-to-4
-  - Name: About the Migration Toolkit for Containers
-    File: migrating-application-workloads-3-4
-  - Name: Installing and upgrading the Migration Toolkit for Containers
-    File: deploying-cam-3-4
-  - Name: Configuring object storage for a replication repository
-    File: configuring-replication-repository-3-4
-  - Name: Migrating your applications
-    File: migrating-applications-with-cam-3-4
-  - Name: Troubleshooting
-    File: troubleshooting-3-4
 - Name: Migrating from OpenShift Container Platform 4.1
   Dir: migrating_4_1_4
   Distros: openshift-enterprise

installing/installing-preparing.adoc

@@ -34,7 +34,7 @@ If you want to use {product-title} but do not want to manage the cluster yoursel
 [id="installing-preparing-migrate"]
 === Have you used {product-title} 3 and want to use {product-title} 4?
 
-If you used {product-title} 3 and want to try {product-title} 4, you need to understand how different {product-title} 4 is. {product-title} 4 weaves the Operators that package, deploy, and manage Kubernetes applications and the operating system that the platform runs on, {op-system-first}, together seamlessly. Instead of deploying machines and configuring their operating systems so that you can install {product-title} on them, the {op-system} operating system is an integral part of the {product-title} cluster. Deploying the operating system for the cluster machines as part of the installation process for {product-title}. See xref:../migration/migrating_3_4/planning-migration-3-to-4.adoc#migration-comparing-ocp-3-4[Comparing OpenShift Container Platform 3 and OpenShift Container Platform 4].
+If you used {product-title} 3 and want to try {product-title} 4, you need to understand how different {product-title} 4 is. {product-title} 4 weaves the Operators that package, deploy, and manage Kubernetes applications and the operating system that the platform runs on, {op-system-first}, together seamlessly. Instead of deploying machines and configuring their operating systems so that you can install {product-title} on them, the {op-system} operating system is an integral part of the {product-title} cluster. Deploying the operating system for the cluster machines as part of the installation process for {product-title}. See xref:../migrating_from_ocp_3_to_4/planning-migration-3-4.adoc#migration-comparing-ocp-3-4[Comparing OpenShift Container Platform 3 and OpenShift Container Platform 4].
 
 Because you need to provision machines as part of the {product-title} cluster installation process, you cannot upgrade an {product-title} 3 cluster to {product-title} 4. Instead, you must create a new {product-title} 4 cluster and migrate your {product-title} 3 workloads to them. For more information about migrating, see link:https://redhat-cop.github.io/openshift-migration-best-practices/01-planning.html[OpenShift Migration Best Practices]. Because you must migrate to {product-title} 4, you can use any type of production cluster installation process to create your new cluster.
 

…ation/migrating_3_4/about-migration.adoc …_3_to_4/about-migrating-from-3-to-4.adocmigration/migrating_3_4/about-migration.adoc renamed to migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc migration/migrating_3_4/about-migration.adoc renamed to migrating_from_ocp_3_to_4/about-migrating-from-3-to-4.adoc

@@ -1,16 +1,16 @@
-[id="about-migration"]
-= About migrating {product-title} 3 to 4
+[id="about-migrating-from-3-to-4"]
+= About migrating from {product-title} 3 to 4
 include::modules/common-attributes.adoc[]
-:context: about-migration
+:context: about-migrating-from-3-to-4
 
 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.
 
 To successfully transition from {product-title} 3 to {product-title} 4, it is important that you review the following information:
 
-xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#planning-migration-3-to-4[Planning your transition]::
+xref:../migrating_from_ocp_3_to_4/planning-migration-3-4.adoc#planning-migration-3-4[Planning your transition]::
 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.
 
-xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migrating-application-workloads-3-4[Performing your migration]::
-Learn about and use {mtc-full} ({mtc-short}) to migrate your application workloads.
+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.

…migrating-application-workloads-3-4.adoc …ating_from_ocp_3_to_4/about-mtc-3-4.adocmigration/migrating_3_4/migrating-application-workloads-3-4.adoc renamed to migrating_from_ocp_3_to_4/about-mtc-3-4.adoc migration/migrating_3_4/migrating-application-workloads-3-4.adoc renamed to migrating_from_ocp_3_to_4/about-mtc-3-4.adoc

@@ -1,40 +1,28 @@
-[id="migrating-application-workloads-3-4"]
+[id="about-mtc-3-4"]
 = About the {mtc-full}
 include::modules/common-attributes.adoc[]
-:context: migrating-3-4
-:migrating-3-4:
+:context: about-mtc-3-4
 
 toc::[]
 
+The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace.
+
 You can migrate application workloads from {product-title} 3.7, 3.9, 3.10, and 3.11 to {product-title} {product-version} with the {mtc-full} ({mtc-short}). {mtc-short} enables you to control the migration and to minimize application downtime.
 
-[NOTE]
+[IMPORTANT]
 ====
-{mtc-short} is installed on the target cluster by default.
-
-You can configure the {mtc-full} Operator to install the {mtc-short} link:https://access.redhat.com/articles/5064151[on an {product-title} 3 cluster or on a remote cluster].
+Before you begin your migration, be sure to review the information on xref:../migrating_from_ocp_3_to_4/planning-migration-3-4.adoc#planning-migration-3-4[planning your migration].
 ====
 
-The {mtc-short} web console and API, based on Kubernetes custom resources, enable you to migrate stateful application workloads at the granularity of a namespace.
+The {mtc-short} console is installed on the target cluster by default. You can configure the {mtc-full} Operator to install the console on an link:https://access.redhat.com/articles/5064151[{product-title} 3 source cluster or on a 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.
 
 You can use migration hooks to run Ansible playbooks at certain points during the migration. The hooks are added when you create a migration plan.
 
-[NOTE]
-====
-The service catalog is deprecated in {product-title} 4. You can migrate workload resources provisioned with the service catalog from {product-title} 3 to 4 but you cannot perform service catalog actions such as `provision`, `deprovision`, or `update` on these workloads after migration.
-
-The {mtc-short} web console displays a message if the service catalog resources cannot be migrated.
-====
-
-[IMPORTANT]
-====
-Before you begin your migration, be sure to review the information on xref:../../migration/migrating_3_4/planning-migration-3-to-4.adoc#planning-migration-3-to-4[planning your migration].
-====
+The service catalog is deprecated in {product-title} 4. You can migrate workload resources provisioned with the service catalog from {product-title} 3 to 4 but you cannot perform service catalog actions such as `provision`, `deprovision`, or `update` on these workloads after migration. The {mtc-short} console displays a message if the service catalog resources cannot be migrated.
 
 include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
 include::modules/migration-mtc-custom-resources.adoc[leveloffset=+1]
 include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
 include::modules/migration-about-migration-hooks.adoc[leveloffset=+1]
-:!migrating-3-4:

migrating_from_ocp_3_to_4/configuring-replication-repository-3-4.adoc

@@ -0,0 +1,30 @@
+[id="configuring-replication-repository-3-4"]
+= Configuring object storage for a replication repository
+include::modules/common-attributes.adoc[]
+:context: configuring-replication-repository-3-4
+
+toc::[]
+
+You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster.
+
+{mtc-short} supports the xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-understanding-data-copy-methods_about-mtc-3-4[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.
+
+The following storage providers are supported:
+
+* xref:../migrating_from_ocp_3_to_4/configuring-replication-repository-3-4.adoc#migration-configuring-mcg_configuring-replication-repository-3-4[Multi-Cloud Object Gateway (MCG)]
+* xref:../migrating_from_ocp_3_to_4/configuring-replication-repository-3-4.adoc#migration-configuring-aws-s3_configuring-replication-repository-3-4[Amazon Web Services (AWS) S3]
+* xref:../migrating_from_ocp_3_to_4/configuring-replication-repository-3-4.adoc#migration-configuring-gcp_configuring-replication-repository-3-4[Google Cloud Provider (GCP)]
+* xref:../migrating_from_ocp_3_to_4/configuring-replication-repository-3-4.adoc#migration-configuring-azure_configuring-replication-repository-3-4[Microsoft Azure]
+* Generic S3 object storage, for example, Minio or Ceph S3
+
+In a restricted environment, you can create an internally hosted replication repository.
+
+.Prerequisites
+
+* All clusters must have uninterrupted network access to the replication repository.
+* If you use a proxy server with an internally hosted replication repository, you must ensure that the proxy allows access to the replication repository.
+
+include::modules/migration-configuring-mcg.adoc[leveloffset=+1]
+include::modules/migration-configuring-aws-s3.adoc[leveloffset=+1]
+include::modules/migration-configuring-gcp.adoc[leveloffset=+1]
+include::modules/migration-configuring-azure.adoc[leveloffset=+1]

migrating_from_ocp_3_to_4/images

@@ -0,0 +1 @@
+../images

migrating_from_ocp_3_to_4/installing-3-4.adoc

@@ -0,0 +1,47 @@
+[id="installing-3-4"]
+= Installing the Migration Toolkit for Containers
+include::modules/common-attributes.adoc[]
+:context: installing-3-4
+:installing-3-4:
+
+toc::[]
+
+You can install the {mtc-full} ({mtc-short}) on {product-title} 3 and on {product-title} {product-version} clusters.
+
+[IMPORTANT]
+====
+You must install the same {mtc-short} version on all clusters.
+====
+
+By default, the {mtc-short} web console and the `Migration Controller` pod run on the target cluster.
+
+You can configure the `Migration Controller` custom resource manifest to run the {mtc-short} web console and the `Migration Controller` pod on a link:https://access.redhat.com/articles/5064151[source cluster or on a remote cluster].
+
+include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1]
+include::modules/migration-installing-mtc-on-ocp-3.adoc[leveloffset=+1]
+
+[id="configuring-replication-repository_{context}"]
+== Configuring a replication repository
+
+You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster.
+
+{mtc-short} supports the xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-understanding-data-copy-methods_about-mtc-3-4[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.
+
+All clusters must have uninterrupted network access to the replication repository.
+
+If you use a proxy server with an internally hosted replication repository, you must ensure that the proxy allows access to the replication repository.
+
+The following storage providers are supported:
+
+* Multi-Cloud Object Gateway (MCG)
+* Amazon Web Services (AWS) S3
+* Google Cloud Provider (GCP)
+* Microsoft Azure Blob
+* Generic S3 object storage, for example, Minio or Ceph S3
+
+include::modules/migration-configuring-mcg.adoc[leveloffset=+2]
+include::modules/migration-configuring-aws-s3.adoc[leveloffset=+2]
+include::modules/migration-configuring-gcp.adoc[leveloffset=+2]
+include::modules/migration-configuring-azure.adoc[leveloffset=+2]
+
+:installing-3-4!:

migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc

@@ -0,0 +1,38 @@
+[id="installing-restricted-3-4"]
+= Installing the Migration Toolkit for Containers in a restricted network environment
+include::modules/common-attributes.adoc[]
+:context: installing-restricted-3-4
+:installing-restricted-3-4:
+
+toc::[]
+
+You can install the {mtc-full} ({mtc-short}) on {product-title} 3 and on {product-title} {product-version} in a restricted network environment.
+
+[IMPORTANT]
+====
+You must install the same {mtc-short} version on all clusters.
+====
+
+By default, the {mtc-short} web console and the `Migration Controller` pod run on the target cluster.
+
+You can configure the `Migration Controller` custom resource manifest to run the {mtc-short} web console and the `Migration Controller` pod on a link:https://access.redhat.com/articles/5064151[source cluster or on a remote cluster].
+
+You must create an Operator catalog from a mirror image in a local registry. See xref:../operators/admin/olm-restricted-networks.adoc[Using Operator Lifecycle Manager on restricted networks] for instructions.
+
+include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1]
+include::modules/migration-installing-mtc-on-ocp-3.adoc[leveloffset=+1]
+
+[id="configuring-replication-repository_{context}"]
+== Configuring a replication repository
+
+You must configure an object storage to use as a replication repository. The {mtc-full} ({mtc-short}) copies data from the source cluster to the replication repository, and then from the replication repository to the target cluster. Multi-Cloud Object Gateway (MCG) is the only supported option for a restricted network environment.
+
+{mtc-short} supports the xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-understanding-data-copy-methods_about-mtc-3-4[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.
+
+All clusters must have uninterrupted network access to the replication repository.
+
+If you use a proxy server with an internally hosted replication repository, you must ensure that the proxy allows access to the replication repository.
+
+include::modules/migration-configuring-mcg.adoc[leveloffset=+2]
+
+:installing-restricted-3-4!:

…migrating-applications-with-cam-3-4.adoc …p_3_to_4/migrating-applications-3-4.adocmigration/migrating_3_4/migrating-applications-with-cam-3-4.adoc renamed to migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc renamed to migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc

@@ -1,8 +1,7 @@
-[id='migrating-applications-with-cam_{context}']
+[id="migrating-applications-3-4_{context}"]
 = Migrating your applications
 include::modules/common-attributes.adoc[]
-:context: migrating-3-4
-:migrating-3-4:
+:context: migrating-applications-3-4
 
 toc::[]
 
@@ -17,9 +16,9 @@ include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2]
 [id="migrating-applications-additional-resources_{context}"]
 === Additional resources
 
-* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#migration-about-migration-hooks_migrating-3-4[About migration hooks]
-* xref:../../migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc#mighook_migrating-3-4[MigHook custom resource]
-* xref:../../migration/migrating_3_4/migrating-applications-with-cam-3-4.adoc#migplan_migrating-3-4[MigPlan custom resource]
+* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-about-migration-hooks_about-mtc-3-4[About migration hooks]
+* xref:../migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc#mighook_migrating-applications-3-4[MigHook custom resource]
+* xref:../migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc#migplan_migrating-applications-3-4[MigPlan custom resource]
 
 [id="migrating-applications-mtc-web-console_{context}"]
 == Migrating your applications by using the {mtc-short} web console
@@ -35,7 +34,7 @@ include::modules/migration-running-migration-plan-cam.adoc[leveloffset=+2]
 [id="migrating-applications-mtc-cli_{context}"]
 == Migrating your applications from the command line
 
-You can migrate your applications on the command line by using the {mtc-short} custom resources (CRs).
+You can migrate your applications on the command line by creating or editing the {mtc-short} custom resource (CR) manifests.
 
 You can migrate applications from a local cluster to a remote cluster, from a remote cluster to a local cluster, and between remote clusters.
 
@@ -63,16 +62,15 @@ include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2]
 [id="migrating-applications-mtc-cli-additional-resources_{context}"]
 == Additional resources
 
-* xref:../../registry/securing-exposing-registry.adoc#registry-exposing-secure-registry-manually_securing-exposing-registry[Exposing a secure registry manually on an {product-title} 4 cluster]
-* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#file-system-copy-method_migrating-3-4[{mtc-short} file system copy method]
-* xref:../../migration/migrating_3_4/migrating-application-workloads-3-4.adoc#snapshot-copy-method_migrating-3-4[{mtc-short} snapshot copy method]
-* xref:../../migration/migrating_3_4/troubleshooting-3-4.adoc#migration-viewing-migration-crs_migrating-3-4[Viewing migration custom resources]
+* xref:../registry/securing-exposing-registry.adoc#registry-exposing-secure-registry-manually_securing-exposing-registry[Exposing a secure registry manually on an {product-title} 4 cluster]
+* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#file-system-copy-method_about-mtc-3-4[{mtc-short} file system copy method]
+* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#snapshot-copy-method_about-mtc-3-4[{mtc-short} snapshot copy method]
+* xref:../migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc#migration-viewing-migration-crs_troubleshooting-3-4[Viewing migration custom resources]
 
-[id='configuring-migration-plan_{context}']
+[id="configuring-migration-plan_{context}"]
 == Configuring a migration plan
 
 You can increase the number of objects to be migrated or exclude resources from the migration.
 
 include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2]
 include::modules/migration-excluding-resources.adoc[leveloffset=+2]
-:!migrating-3-4:

migrating_from_ocp_3_to_4/modules

@@ -0,0 +1 @@
+../modules