From 0c642981996b146ceca88fb6476eafbe1226b326 Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Mon, 4 Oct 2021 12:43:18 +0300 Subject: [PATCH] [enterprise-4.6] MIG-813: Intracluster migration --- .../advanced-migration-options-3-4.adoc | 11 ++++------- .../migrating-applications-3-4.adoc | 12 +++++++++++- migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc | 8 -------- migration_toolkit_for_containers/about-mtc.adoc | 2 ++ .../advanced-migration-options-mtc.adoc | 14 ++++++-------- .../migrating-applications-with-mtc.adoc | 2 +- .../troubleshooting-mtc.adoc | 8 -------- modules/migration-about-state-migration.adoc | 6 ++++-- modules/migration-running-migration-plan-cam.adoc | 7 +++---- modules/migration-state-migration-cli.adoc | 13 ++++++++++--- 10 files changed, 41 insertions(+), 42 deletions(-) diff --git a/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc b/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc index f538d3a2e933..1be0fedc18e2 100644 --- a/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +++ b/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] diff --git a/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc b/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc index 75518c265814..cc37770c8d5f 100644 --- a/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc +++ b/migrating_from_ocp_3_to_4/migrating-applications-3-4.adoc @@ -5,7 +5,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. include::modules/migration-prerequisites.adoc[leveloffset=+1] diff --git a/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc b/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc index 52859e2a4eca..bd25ceab45a8 100644 --- a/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc +++ b/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc @@ -21,14 +21,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 diff --git a/migration_toolkit_for_containers/about-mtc.adoc b/migration_toolkit_for_containers/about-mtc.adoc index df6582d20c57..51074a596e6d 100644 --- a/migration_toolkit_for_containers/about-mtc.adoc +++ b/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]. diff --git a/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc index 9ea1567b2f91..1639f83b7e7a 100644 --- a/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc +++ b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc @@ -5,23 +5,21 @@ 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] @@ -29,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] diff --git a/migration_toolkit_for_containers/migrating-applications-with-mtc.adoc b/migration_toolkit_for_containers/migrating-applications-with-mtc.adoc index a872f3b1a1f2..020ad1a1f72d 100644 --- a/migration_toolkit_for_containers/migrating-applications-with-mtc.adoc +++ b/migration_toolkit_for_containers/migrating-applications-with-mtc.adoc @@ -5,7 +5,7 @@ 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]. include::modules/migration-prerequisites.adoc[leveloffset=+1] diff --git a/migration_toolkit_for_containers/troubleshooting-mtc.adoc b/migration_toolkit_for_containers/troubleshooting-mtc.adoc index 8efe3a14d237..26a9617878d5 100644 --- a/migration_toolkit_for_containers/troubleshooting-mtc.adoc +++ b/migration_toolkit_for_containers/troubleshooting-mtc.adoc @@ -21,14 +21,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 diff --git a/modules/migration-about-state-migration.adoc b/modules/migration-about-state-migration.adoc index 40f655e68fa1..3ff00f53ae29 100644 --- a/modules/migration-about-state-migration.adoc +++ b/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. ==== diff --git a/modules/migration-running-migration-plan-cam.adoc b/modules/migration-running-migration-plan-cam.adoc index e473960645f7..97572932387f 100644 --- a/modules/migration-running-migration-plan-cam.adoc +++ b/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*. diff --git a/modules/migration-state-migration-cli.adoc b/modules/migration-state-migration-cli.adoc index 3228d844c0e2..bf8e87ac6854 100644 --- a/modules/migration-state-migration-cli.adoc +++ b/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] ====