Merge pull request #45441 from sbeskin-redhat/MIG_1045_Instructions_for_state_only_transfer_and_CD_migration

MIG-1045 Instructions for state-only transfer and CD migration

Author: stevsmit

modules/migration-state-migration-cli.adoc

@@ -3,18 +3,91 @@
 // * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc
 // * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc
 
+:_content-type: PROCEDURE
 [id="migration-state-migration-cli_{context}"]
 = State migration
 
-You can perform repeatable, state-only migrations by using {mtc-full} ({mtc-short}) to migrate persistent volume claims (PVCs) that constitute an application's state. You migrate specified PVCs by excluding other PVCs from the migration plan. Persistent volume (PV) data is copied to the target cluster. The PV references are not moved. The application pods continue to run on the source cluster. You can map the PVCs to ensure that the source and target PVCs are synchronized.
+You can perform repeatable, state-only migrations by using {mtc-full} ({mtc-short}) to migrate persistent volume claims (PVCs) that constitute an application's state. You migrate specified PVCs by excluding other PVCs from the migration plan. You can map the PVCs to ensure that the source and the target PVCs are synchronized. Persistent volume (PV) data is copied to the target cluster. The PV references are not moved, and the application pods continue to run on the source cluster.
 
-You can perform a one-time migration of Kubernetes objects that constitute an application's state.
+State migration is specifically designed to be used in conjunction with external CD mechanisms, such as OpenShift Gitops. You can migrate application manifests using GitOps while migrating the state using {mtc-short}.
 
 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 perform a state migration between clusters or within the same cluster.
+You can perform a state migration between clusters or within the same cluster. 
 
 [IMPORTANT]
 ====
 State migration migrates only the components that constitute an application's state. If you want to migrate an entire namespace, use stage or cutover migration.
 ====
+
+.Prerequisites
+
+* The state of the application on the source cluster is persisted in `PersistentVolumes` provisioned through `PersistentVolumeClaims`.
+
+* The manifests of the application are available in a central repository that is accessible from both the source and the target clusters.
+
+
+.Procedure
+
+. Migrate persistent volume data from the source to the target cluster.
++
+You can perform this step as many times as needed. The source application continues running.
+
+. Quiesce the source application.
++
+You can do this by setting the replicas of workload resources to `0`, either directly on the source cluster or by updating the manifests in GitHub and re-syncing the Argo CD application.
+
+. Clone application manifests to the target cluster.
++
+You can use Argo CD to clone the application manifests to the target cluster.
+
+. Migrate the remaining volume data from the source to the target cluster.
++
+Migrate any new data created by the application during the state migration process by performing a final data migration.
+
+. If the cloned application is in a quiesced state, unquiesce it.
+
+. Switch the DNS record to the target cluster to re-direct user traffic to the migrated application.
+
+[NOTE]
+====
+{mtc-short} 1.6 cannot quiesce applications automatically when performing state migration. It can only migrate PV data. Therefore, you must use your CD mechanisms for quiescing or unquiescing applications.
+
+{mtc-short} 1.7 introduces explicit Stage and Cutover flows. You can use staging to perform initial data transfers as many times as needed. Then you can perform a cutover, in which the source applications are quiesced automatically.
+====
+
+.Prerequisites
+
+* The state of the application on the source cluster is persisted in `PersistentVolumes` provisioned through `PersistentVolumeClaims`.
+
+* The manifests of the application are available in a central repository that is accessible from both the source and the target clusters.
+
+
+.Procedure
+
+. Migrate persistent volume data from the source to the target cluster.
++
+You can perform this step as many times as needed. The source application continues running.
+
+. Quiesce the source application.
++
+You can do this by setting the replicas of workload resources to `0`, either directly on the source cluster or by updating the manifests in GitHub and re-syncing the Argo CD application.
+
+. Clone application manifests to the target cluster.
++
+You can use Argo CD to clone the application manifests to the target cluster.
+
+. Migrate the remaining volume data from the source to the target cluster.
++
+Migrate any new data created by the application during the state migration process by performing a final data migration.
+
+. If the cloned application is in a quiesced state, unquiesce it.
+
+. Switch the DNS record to the target cluster to re-direct user traffic to the migrated application.
+
+[NOTE]
+====
+{mtc-short} 1.6 cannot quiesce applications automatically when performing state migration. It can only migrate PV data. Therefore, you must use your CD mechanisms for quiescing or unquiescing applications.
+
+{mtc-short} 1.7 introduces explicit Stage and Cutover flows. You can use staging to perform initial data transfers as many times as needed. Then you can perform a cutover, in which the source applications are quiesced automatically.
+====