From a7645e0f4fe3a58ce1f540b2475c3d609e4c8d3b Mon Sep 17 00:00:00 2001 From: Avital Pinnick Date: Sun, 5 Sep 2021 11:45:25 +0300 Subject: [PATCH] MIG-803: State migration --- migrating_from_ocp_3_to_4/about-mtc-3-4.adoc | 1 + .../advanced-migration-options-3-4.adoc | 5 +- .../troubleshooting-3-4.adoc | 3 +- .../about-mtc.adoc | 1 + .../troubleshooting-mtc.adoc | 3 +- modules/migration-about-state-migration.adoc | 18 +++ .../migration-migrating-applications-api.adoc | 4 +- .../migration-running-migration-plan-cam.adoc | 21 +++- modules/migration-state-migration-cli.adoc | 119 ++++++++++++++++++ 9 files changed, 163 insertions(+), 12 deletions(-) create mode 100644 modules/migration-about-state-migration.adoc create mode 100644 modules/migration-state-migration-cli.adoc diff --git a/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc b/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc index d6b9273e3f32..f908405dd169 100644 --- a/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc +++ b/migrating_from_ocp_3_to_4/about-mtc-3-4.adoc @@ -23,3 +23,4 @@ The service catalog is deprecated in {product-title} 4. You can migrate workload include::modules/migration-terminology.adoc[leveloffset=+1] include::modules/migration-mtc-workflow.adoc[leveloffset=+1] include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] +include::modules/migration-about-state-migration.adoc[leveloffset=+1] 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 22f12510478c..f538d3a2e933 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 @@ -14,14 +14,15 @@ 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 from the command line -This section describes how to migrate your applications with the {mtc-short} API from the command line interface (CLI). +This section describes how to migrate applications with the {mtc-short} API from the command line interface (CLI). 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-migrating-applications-api.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] 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 d32405847f84..1f644e304af8 100644 --- a/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc +++ b/migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc @@ -28,7 +28,8 @@ include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2 === 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[{mtc-short} custom resources] +* 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 c096cf897215..df6582d20c57 100644 --- a/migration_toolkit_for_containers/about-mtc.adoc +++ b/migration_toolkit_for_containers/about-mtc.adoc @@ -19,3 +19,4 @@ See xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc include::modules/migration-terminology.adoc[leveloffset=+1] include::modules/migration-mtc-workflow.adoc[leveloffset=+1] include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1] +include::modules/migration-about-state-migration.adoc[leveloffset=+1] diff --git a/migration_toolkit_for_containers/troubleshooting-mtc.adoc b/migration_toolkit_for_containers/troubleshooting-mtc.adoc index 62fdb35b53f2..afe79d751834 100644 --- a/migration_toolkit_for_containers/troubleshooting-mtc.adoc +++ b/migration_toolkit_for_containers/troubleshooting-mtc.adoc @@ -28,7 +28,8 @@ include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2 === 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[{mtc-short} custom resources] +* 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 new file mode 100644 index 000000000000..40f655e68fa1 --- /dev/null +++ b/modules/migration-about-state-migration.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc +// * migration_toolkit_for_containers/about-mtc.adoc + +[id="migration-state-migration_{context}"] += State migration + +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. + +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}. + +[IMPORTANT] +==== +Do not use state migration to migrate a namespace. +==== diff --git a/modules/migration-migrating-applications-api.adoc b/modules/migration-migrating-applications-api.adoc index 2779118be5ae..bfc5ad5ffade 100644 --- a/modules/migration-migrating-applications-api.adoc +++ b/modules/migration-migrating-applications-api.adoc @@ -4,9 +4,9 @@ // * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc [id="migration-migrating-applications-api_{context}"] -= Migrating your applications from the command line += Migrating an application from the command line -You can migrate your applications from the command line with the {mtc-full} ({mtc-short}) API. +You can migrate an application from the command line by using the {mtc-full} ({mtc-short}) API. .Procedure diff --git a/modules/migration-running-migration-plan-cam.adoc b/modules/migration-running-migration-plan-cam.adoc index a37b031adf2f..e473960645f7 100644 --- a/modules/migration-running-migration-plan-cam.adoc +++ b/modules/migration-running-migration-plan-cam.adoc @@ -6,7 +6,7 @@ [id="migration-running-migration-plan-cam_{context}"] = Running a migration plan in the {mtc-short} web console -You can stage or migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console. +You can migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console. [NOTE] ==== @@ -27,14 +27,23 @@ The {mtc-short} web console must contain the following: .Procedure . Log in to the {mtc-short} web console and click *Migration plans*. -. Click the *Options* menu {kebab} next to a migration plan and select *Stage* to copy data from the source cluster to the target cluster without stopping the application. +. 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. + +* *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. + -You can run *Stage* multiple times to reduce the actual migration time. +[IMPORTANT] +==== +Do not use state migration to migrate a namespace. +==== -. When you are ready to migrate the application workload, the *Options* menu {kebab} beside a migration plan and select *Migrate*. +** Select one or more PVCs in the *State migration* dialog and click *Migrate*. -. Optional: In the *Migrate* window, you can select *Do not stop applications on the source cluster during migration*. -. Click *Migrate*. . When the migration is complete, verify that the application migrated successfully in the {product-title} web console: .. Click *Home* -> *Projects*. diff --git a/modules/migration-state-migration-cli.adoc b/modules/migration-state-migration-cli.adoc new file mode 100644 index 000000000000..3228d844c0e2 --- /dev/null +++ b/modules/migration-state-migration-cli.adoc @@ -0,0 +1,119 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc +// * migration_toolkit_for_containers/about-mtc.adoc + +[id="migration-state-migration-cli_{context}"] += Migrating an application's state + +You can perform repeatable, state-only migrations by selecting specific persistent volume claims (PVCs). During a state migration, {mtc-full} ({mtc-short}) copies persistent volume (PV) data to the target cluster. PV references are not moved. The application pods continue to run on the source cluster. + +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 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. + +[id="excluding-pvcs_{context}"] +== Excluding persistent volume claims + +You can exclude persistent volume claims (PVCs) by adding the `spec.persistentVolumes.pvc.selection.action` parameter to the `MigPlan` custom resource (CR) after the persistent volumes (PVs) have been discovered. + +.Prerequisites + +* `MigPlan` CR with discovered PVs. + +.Procedure + +* Add the `spec.persistentVolumes.pvc.selection.action` parameter to the `MigPlan` CR and set its value to `skip`: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigPlan +metadata: + name: + namespace: openshift-migration +spec: +... + persistentVolumes: + - capacity: 10Gi + name: + pvc: +... + selection: + action: skip <1> +---- +<1> `skip` excludes the PVC from the migration plan. + +[id="mapping-pvcs_{context}"] +== Mapping persistent volume claims + +You can map persistent volume claims (PVCs) by updating the `spec.persistentVolumes.pvc.name` parameter in the `MigPlan` custom resource (CR) after the persistent volumes (PVs) have been discovered. + +.Prerequisites + +* `MigPlan` CR with discovered PVs. + +.Procedure + +* Update the `spec.persistentVolumes.pvc.name` parameter in the `MigPlan` CR: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigPlan +metadata: + name: + namespace: openshift-migration +spec: +... + persistentVolumes: + - capacity: 10Gi + name: + pvc: + name: : <1> +---- +<1> Specify the PVC on the source cluster and the PVC on the destination cluster. If the destination PVC does not exist, it will be created. You can use this mapping to change the PVC name during migration. + +[id="migrating-kubernetes-objects_{context}"] +== Migrating Kubernetes objects + +You can perform a one-time migration of Kubernetes objects that store an application's state. + +[NOTE] +==== +After migration, the `closed` parameter of the `MigPlan` CR is set to `true`. You cannot create another `MigMigration` CR for this `MigPlan` CR. +==== + +You add Kubernetes objects to the `MigPlan` CR by using the following options: + +* Adding the Kubernetes objects to the `includedResources` section. +* Using the `labelSelector` parameter to reference labeled Kubernetes objects. + +If you set both parameters, the label is used to filter the included resources, for example, to migrate `Secret` and `ConfigMap` resources with the label `app: frontend`. + +.Procedure + +* Update the `MigPlan` CR: ++ +[source,yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigPlan +metadata: + name: + namespace: openshift-migration +spec: + includedResources: <1> + - kind: + group: "" + - kind: + group: "" +... + labelSelector: + matchLabels: + <2> +---- +<1> Specify the `kind` and `group` of each resource. +<2> Specify the label of the resources to migrate.