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 f908405dd169..d6b9273e3f32 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,4 +23,3 @@ 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 1be0fedc18e2..f098eb0f2486 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 @@ -19,7 +19,11 @@ 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-state-migration-cli.adoc[leveloffset=+1] +include::modules/migration-excluding-pvcs.adoc[leveloffset=+2] +include::modules/migration-mapping-pvcs.adoc[leveloffset=+2] +include::modules/migration-kubernetes-objects.adoc[leveloffset=+2] include::modules/migration-hooks.adoc[leveloffset=+1] include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] diff --git a/migration_toolkit_for_containers/about-mtc.adoc b/migration_toolkit_for_containers/about-mtc.adoc index 51074a596e6d..5ef8a113dde6 100644 --- a/migration_toolkit_for_containers/about-mtc.adoc +++ b/migration_toolkit_for_containers/about-mtc.adoc @@ -21,4 +21,3 @@ 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/advanced-migration-options-mtc.adoc b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc index 1639f83b7e7a..41cac02855bb 100644 --- a/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc +++ b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc @@ -19,7 +19,11 @@ 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-mapping-destination-namespaces-in-the-migplan-cr.adoc[leveloffset=+2] -include::modules/migration-state-migration-cli.adoc[leveloffset=+2] + +include::modules/migration-state-migration-cli.adoc[leveloffset=+1] +include::modules/migration-excluding-pvcs.adoc[leveloffset=+2] +include::modules/migration-mapping-pvcs.adoc[leveloffset=+2] +include::modules/migration-kubernetes-objects.adoc[leveloffset=+2] include::modules/migration-hooks.adoc[leveloffset=+1] include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2] diff --git a/modules/migration-about-state-migration.adoc b/modules/migration-about-state-migration.adoc deleted file mode 100644 index 3ff00f53ae29..000000000000 --- a/modules/migration-about-state-migration.adoc +++ /dev/null @@ -1,20 +0,0 @@ -// 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 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 namespaces between clusters. Use stage or cutover migration instead. -==== diff --git a/modules/migration-excluding-pvcs.adoc b/modules/migration-excluding-pvcs.adoc new file mode 100644 index 000000000000..d1ec9ccd8892 --- /dev/null +++ b/modules/migration-excluding-pvcs.adoc @@ -0,0 +1,35 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc + +[id="migration-excluding-pvcs_{context}"] += Excluding persistent volume claims + +You select persistent volume claims (PVCs) for state migration by excluding the PVCs that you do not want to migrate. You exclude PVCs by setting the `spec.persistentVolumes.pvc.selection.action` parameter of 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 it 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 +---- diff --git a/modules/migration-kubernetes-objects.adoc b/modules/migration-kubernetes-objects.adoc new file mode 100644 index 000000000000..15e64534bf3c --- /dev/null +++ b/modules/migration-kubernetes-objects.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc + +[id="migration-kubernetes-objects_{context}"] += Migrating Kubernetes objects + +You can perform a one-time migration of Kubernetes objects that constitute 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 one of the following options: + +* Adding the Kubernetes objects to the `includedResources` section. +* Using the `labelSelector` parameter to reference labeled Kubernetes objects. +* Adding Kubernetes objects to the `includedResources` section and then filtering them with the `labelSelector` parameter, for example, `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. diff --git a/modules/migration-mapping-pvcs.adoc b/modules/migration-mapping-pvcs.adoc new file mode 100644 index 000000000000..3a71c2767085 --- /dev/null +++ b/modules/migration-mapping-pvcs.adoc @@ -0,0 +1,36 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +// * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc + +[id="migration-mapping-pvcs_{context}"] += Mapping persistent volume claims + +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 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. diff --git a/modules/migration-state-migration-cli.adoc b/modules/migration-state-migration-cli.adoc index bf8e87ac6854..3a8fc1e36e14 100644 --- a/modules/migration-state-migration-cli.adoc +++ b/modules/migration-state-migration-cli.adoc @@ -4,123 +4,17 @@ // * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc [id="migration-state-migration-cli_{context}"] -= Migrating an application's state += State migration -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. +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. 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 perform a one-time migration of 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 stateful components by using {mtc-short}. -You can use state migration to migrate namespaces within the same cluster. +You can perform a state migration between clusters or within the same cluster. [IMPORTANT] ==== -Do not use state migration to migrate namespaces between clusters. Use stage or cutover migration instead. +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. ==== - -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 constitute 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.