Merge pull request #37016 from apinnick/mig813-intracluster-migration

MIG-831: Intracluster migration

Author: apinnick

migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc

@@ -6,17 +6,14 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-This section describes advanced options for automating your migration and for modifying the migration plan.
+You can automate your migrations and modify the `MigPlan` and `MigrationController` custom resources in order to perform large-scale migrations and to improve performance.
 
 include::modules/migration-terminology.adoc[leveloffset=+1]
-include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
-include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+1]
-include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+1]
 
 [id="migrating-your-applications-api_{context}"]
-== Migrating applications from the command line
+== Migrating applications by using the CLI
 
-This section describes how to migrate applications with the {mtc-short} API from the command line interface (CLI).
+You can migrate applications with the {mtc-short} API by using the command line interface (CLI) in order to automate the migration.
 
 include::modules/migration-prerequisites.adoc[leveloffset=+2]
 include::modules/migration-creating-registry-route-for-dim.adoc[leveloffset=+2]
@@ -30,7 +27,7 @@ include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2]
 [id="configuration-options_{context}"]
 == Configuration options
 
-You can configure the following options for the `MigPlan` and `MigrationController` CRs.
+You can configure the following options for the `MigPlan` and `MigrationController` custom resources (CRs) to perform large-scale migrations and to improve performance.
 
 include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2]
 include::modules/migration-excluding-resources.adoc[leveloffset=+2]

migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc

@@ -6,7 +6,17 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the command line.
+You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#migrating-your-applications-api_advanced-migration-options-3-4[command line].
+
+You can use stage migration and cutover migration to migrate an application between clusters:
+
+* Stage migration copies data from the source cluster to the target cluster without stopping the application. You can run a stage migration multiple times to reduce the duration of the cutover migration.
+* Cutover migration stops the transactions on the source cluster and moves the resources to the target cluster.
+
+You can use state migration to migrate an application's state:
+
+* State migration copies selected persistent volume claims (PVCs) and Kubernetes resources.
+* You can use state migration to migrate a namespace within the same cluster.
 
 Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster.
 

migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc

@@ -10,6 +10,10 @@ This section describes resources for troubleshooting the {mtc-full} ({mtc-short}
 
 For known issues, see the xref:../migration_toolkit_for_containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
 
+include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
+include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+2]
+include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2]
+
 [id="logs-and-debugging-tools_{context}"]
 == Logs and debugging tools
 
@@ -23,14 +27,6 @@ include::modules/migration-debugging-velero-resources.adoc[leveloffset=+2]
 include::modules/migration-partial-failure-velero.adoc[leveloffset=+2]
 include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2]
 
-[id="additional-resources-for-debugging-tools_{context}"]
-[discrete]
-=== Additional resources for debugging tools
-
-* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-mtc-workflow_about-mtc-3-4[{mtc-short} workflow]
-* xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#migration-about-mtc-custom-resources_advanced-migration-options-3-4[About {mtc-short} custom resources]
-* xref:../migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc#migration-mtc-cr-manifests_advanced-migration-options-3-4[{mtc-short} custom resource manifests]
-
 [id="common-issues-and-concerns_{context}"]
 == Common issues and concerns
 

migration_toolkit_for_containers/about-mtc.adoc

@@ -7,6 +7,8 @@ toc::[]
 
 The {mtc-full} ({mtc-short}) enables you to migrate stateful application workloads between {product-title} 4 clusters at the granularity of a namespace.
 
+You can migrate applications within the same cluster by using state migration.
+
 {mtc-short} provides a web console and an API, based on Kubernetes custom resources, to help you control the migration and minimize application downtime.
 
 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].

migration_toolkit_for_containers/advanced-migration-options-mtc.adoc

@@ -5,31 +5,29 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-This section describes advanced options for automating your migration and for modifying the migration plan.
+You can automate your migrations and modify the `MigPlan` and `MigrationController` custom resources in order to perform large-scale migrations and to improve performance.
 
 include::modules/migration-terminology.adoc[leveloffset=+1]
-include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
-include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+1]
-include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+1]
 
 [id="migrating-your-applications-api_{context}"]
-== Migrating your applications with the {mtc-short} API
+== Migrating applications by using the CLI
 
-This section describes how to migrate your applications with the {mtc-short} API from the command line interface (CLI).
+You can migrate applications with the {mtc-short} API by using the command line interface (CLI) in order to automate the migration.
 
 include::modules/migration-prerequisites.adoc[leveloffset=+2]
 include::modules/migration-creating-registry-route-for-dim.adoc[leveloffset=+2]
 include::modules/migration-configuring-proxies.adoc[leveloffset=+2]
-include::modules/migration-mapping-destination-namespaces-in-the-migplan-cr.adoc[leveloffset=+2]
 include::modules/migration-migrating-applications-api.adoc[leveloffset=+2]
+include::modules/migration-mapping-destination-namespaces-in-the-migplan-cr.adoc[leveloffset=+2]
+include::modules/migration-state-migration-cli.adoc[leveloffset=+2]
 
 include::modules/migration-hooks.adoc[leveloffset=+1]
 include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2]
 
 [id="configuration-options_{context}"]
 == Configuration options
 
-You can configure the following options for the `MigPlan` and `MigrationController` CRs.
+You can configure the following options for the `MigPlan` and `MigrationController` custom resources (CRs) to perform large-scale migrations and to improve performance.
 
 include::modules/migration-changing-migration-plan-limits.adoc[leveloffset=+2]
 include::modules/migration-excluding-resources.adoc[leveloffset=+2]

migration_toolkit_for_containers/migrating-applications-with-mtc.adoc

@@ -5,10 +5,20 @@ include::modules/common-attributes.adoc[]
 
 toc::[]
 
-You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the command line.
+You can migrate your applications by using the {mtc-full} ({mtc-short}) web console or from the xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-migrating-applications-api_advanced-migration-options-mtc[command line].
 
 Most cluster-scoped resources are not yet handled by {mtc-short}. If your applications require cluster-scoped resources, you might have to create them manually on the target cluster.
 
+You can use stage migration and cutover migration to migrate an application between clusters:
+
+* Stage migration copies data from the source cluster to the target cluster without stopping the application. You can run a stage migration multiple times to reduce the duration of the cutover migration.
+* Cutover migration stops the transactions on the source cluster and moves the resources to the target cluster.
+
+You can use state migration to migrate an application's state:
+
+* State migration copies selected persistent volume claims (PVCs) and Kubernetes resources.
+* You can use state migration to migrate a namespace within the same cluster.
+
 During migration, the {mtc-full} ({mtc-short}) preserves the following namespace annotations:
 
 * `openshift.io/sa.scc.mcs`

migration_toolkit_for_containers/troubleshooting-mtc.adoc

@@ -10,6 +10,10 @@ This section describes resources for troubleshooting the {mtc-full} ({mtc-short}
 
 For known issues, see the xref:../migration_toolkit_for_containers/mtc-release-notes.adoc#mtc-release-notes[{mtc-short} release notes].
 
+include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
+include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+2]
+include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+2]
+
 [id="logs-and-debugging-tools_{context}"]
 == Logs and debugging tools
 
@@ -23,14 +27,6 @@ include::modules/migration-debugging-velero-resources.adoc[leveloffset=+2]
 include::modules/migration-partial-failure-velero.adoc[leveloffset=+2]
 include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2]
 
-[id="additional-resources-for-debugging-tools_{context}"]
-[discrete]
-=== Additional resources for debugging tools
-
-* xref:../migration_toolkit_for_containers/about-mtc.adoc#migration-mtc-workflow_about-mtc[{mtc-short} workflow]
-* xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-about-mtc-custom-resources_advanced-migration-options-mtc[About {mtc-short} custom resources]
-* xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-mtc-cr-manifests_advanced-migration-options-mtc[{mtc-short} custom resource manifests]
-
 [id="common-issues-and-concerns_{context}"]
 == Common issues and concerns
 

modules/migration-about-state-migration.adoc

@@ -8,11 +8,13 @@
 
 You can use {mtc-full} ({mtc-short}) to migrate an application's state.
 
-State migration copies selected persistent volume claims (PVCs) and Kubernetes objects that store an application's state.
+State migration copies selected persistent volume claims (PVCs) and Kubernetes objects that constitute an application's state.
 
 If you have a CI/CD pipeline, you can migrate stateless components by deploying them on the target cluster. Then you can migrate the application's state by using {mtc-short}.
 
+You can migrate an application within the same cluster by using state migration.
+
 [IMPORTANT]
 ====
-Do not use state migration to migrate a namespace.
+Do not use state migration to migrate namespaces between clusters. Use stage or cutover migration instead.
 ====

modules/migration-running-migration-plan-cam.adoc

@@ -29,17 +29,16 @@ The {mtc-short} web console must contain the following:
 . Log in to the {mtc-short} web console and click *Migration plans*.
 . Click the Options menu {kebab} next to a migration plan and select one of the following options under *Migration*:
 
-* *Stage* copies data from the source cluster to the target cluster without stopping the application. You can run a stage migration multiple times to reduce the duration of the cutover migration.
-
+* *Stage* copies data from the source cluster to the target cluster without stopping the application.
 * *Cutover* stops the transactions on the source cluster and moves the resources to the target cluster.
 +
 Optional: In the *Cutover migration* dialog, you can clear the *Halt transactions on the source cluster during migration* checkbox.
 
-* *State* copies selected persistent volume claims (PVCs) and Kubernetes resources that store an application's state.
+* *State* copies selected persistent volume claims (PVCs) and Kubernetes resources that constitute an application's state. You can use state migration to migrate a namespace within the same cluster.
 +
 [IMPORTANT]
 ====
-Do not use state migration to migrate a namespace.
+Do not use state migration to migrate a namespace between clusters. Use stage or cutover migration instead.
 ====
 
 ** Select one or more PVCs in the *State migration* dialog and click *Migrate*.

modules/migration-state-migration-cli.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
-// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc
-// * migration_toolkit_for_containers/about-mtc.adoc
+// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc
+// * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc
 
 [id="migration-state-migration-cli_{context}"]
 = Migrating an application's state
@@ -10,6 +10,13 @@ You can perform repeatable, state-only migrations by selecting specific persiste
 
 If you have a CI/CD pipeline, you can migrate stateless components by deploying them on the target cluster. Then you can migrate stateful components by using {mtc-short}.
 
+You can use state migration to migrate namespaces within the same cluster.
+
+[IMPORTANT]
+====
+Do not use state migration to migrate namespaces between clusters. Use stage or cutover migration instead.
+====
+
 You can migrate PV data from the source cluster to PVCs that are already provisioned in the target cluster by mapping PVCs in the `MigPlan` CR. This ensures that the target PVCs of migrated applications are synchronized with the source PVCs.
 
 You can perform a one-time migration of Kubernetes objects that store application state.
@@ -79,7 +86,7 @@ spec:
 [id="migrating-kubernetes-objects_{context}"]
 == Migrating Kubernetes objects
 
-You can perform a one-time migration of Kubernetes objects that store an application's state.
+You can perform a one-time migration of Kubernetes objects that constitute an application's state.
 
 [NOTE]
 ====