openshift · vikram-redhat · Sep 29, 2021 · Sep 5, 2021
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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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: <migplan>
+  namespace: openshift-migration
+spec:
+...
+  persistentVolumes:
+  - capacity: 10Gi
+    name: <pv_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: <migplan>
+  namespace: openshift-migration
+spec:
+...
+  persistentVolumes:
+  - capacity: 10Gi
+    name: <pv_name>
+    pvc:
+      name: <source_pvc>:<destination_pvc> <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: <migplan>
+  namespace: openshift-migration
+spec:
+  includedResources: <1>
+  - kind: <Secret>
+    group: ""
+  - kind: <ConfigMap>
+    group: ""
+...
+  labelSelector:
+    matchLabels:
+      <app: frontend> <2>
+----
+<1> Specify the `kind` and `group` of each resource.
+<2> Specify the label of the resources to migrate.