Skip to content

Commit 0572bcd

Browse files
apinnickapinnick
authored
Merge pull request #36095 from apinnick/mig-803-state-migration
MIG-803: State migration (MTC 1.6.0)
2 parents 03d6355 + b25334f commit 0572bcd

File tree

9 files changed

+163
-12
lines changed

9 files changed

+163
-12
lines changed

‎migrating_from_ocp_3_to_4/about-mtc-3-4.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ The service catalog is deprecated in {product-title} 4. You can migrate workload
2323
include::modules/migration-terminology.adoc[leveloffset=+1]
2424
include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
2525
include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
26+
include::modules/migration-about-state-migration.adoc[leveloffset=+1]

‎migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,14 +14,15 @@ include::modules/migration-about-mtc-custom-resources.adoc[leveloffset=+1]
1414
include::modules/migration-mtc-cr-manifests.adoc[leveloffset=+1]
1515

1616
[id="migrating-your-applications-api_{context}"]
17-
== Migrating your applications with the {mtc-short} API
17+
== Migrating applications from the command line
1818

19-
This section describes how to migrate your applications with the {mtc-short} API from the command line interface (CLI).
19+
This section describes how to migrate applications with the {mtc-short} API from the command line interface (CLI).
2020

2121
include::modules/migration-prerequisites.adoc[leveloffset=+2]
2222
include::modules/migration-creating-registry-route-for-dim.adoc[leveloffset=+2]
2323
include::modules/migration-configuring-proxies.adoc[leveloffset=+2]
2424
include::modules/migration-migrating-applications-api.adoc[leveloffset=+2]
25+
include::modules/migration-state-migration-cli.adoc[leveloffset=+2]
2526

2627
include::modules/migration-hooks.adoc[leveloffset=+1]
2728
include::modules/migration-writing-ansible-playbook-hook.adoc[leveloffset=+2]

‎migrating_from_ocp_3_to_4/troubleshooting-3-4.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2
2828
=== Additional resources for debugging tools
2929

3030
* xref:../migrating_from_ocp_3_to_4/about-mtc-3-4.adoc#migration-mtc-workflow_about-mtc-3-4[{mtc-short} workflow]
31-
* 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]
31+
* 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]
32+
* 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]
3233

3334
[id="common-issues-and-concerns_{context}"]
3435
== Common issues and concerns

‎migration_toolkit_for_containers/about-mtc.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ See xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc
1919
include::modules/migration-terminology.adoc[leveloffset=+1]
2020
include::modules/migration-mtc-workflow.adoc[leveloffset=+1]
2121
include::modules/migration-understanding-data-copy-methods.adoc[leveloffset=+1]
22+
include::modules/migration-about-state-migration.adoc[leveloffset=+1]

‎migration_toolkit_for_containers/troubleshooting-mtc.adoc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ include::modules/migration-using-mtc-crs-for-troubleshooting.adoc[leveloffset=+2
2828
=== Additional resources for debugging tools
2929

3030
* xref:../migration_toolkit_for_containers/about-mtc.adoc#migration-mtc-workflow_about-mtc[{mtc-short} workflow]
31-
* xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-about-mtc-custom-resources_advanced-migration-options-mtc[{mtc-short} custom resources]
31+
* xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-about-mtc-custom-resources_advanced-migration-options-mtc[About {mtc-short} custom resources]
32+
* xref:../migration_toolkit_for_containers/advanced-migration-options-mtc.adoc#migration-mtc-cr-manifests_advanced-migration-options-mtc[{mtc-short} custom resource manifests]
3233

3334
[id="common-issues-and-concerns_{context}"]
3435
== Common issues and concerns

‎modules/migration-about-state-migration.adoc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc
4+
// * migration_toolkit_for_containers/about-mtc.adoc
5+
6+
[id="migration-state-migration_{context}"]
7+
= State migration
8+
9+
You can use {mtc-full} ({mtc-short}) to migrate an application's state.
10+
11+
State migration copies selected persistent volume claims (PVCs) and Kubernetes objects that store an application's state.
12+
13+
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}.
14+
15+
[IMPORTANT]
16+
====
17+
Do not use state migration to migrate a namespace.
18+
====

‎modules/migration-migrating-applications-api.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
// * migration_toolkit_for_containers/advanced-migration-options-mtc.adoc
55

66
[id="migration-migrating-applications-api_{context}"]
7-
= Migrating your applications from the command line
7+
= Migrating an application from the command line
88

9-
You can migrate your applications from the command line with the {mtc-full} ({mtc-short}) API.
9+
You can migrate an application from the command line by using the {mtc-full} ({mtc-short}) API.
1010

1111
.Procedure
1212

‎modules/migration-running-migration-plan-cam.adoc‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[id="migration-running-migration-plan-cam_{context}"]
77
= Running a migration plan in the {mtc-short} web console
88

9-
You can stage or migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console.
9+
You can migrate applications and data with the migration plan you created in the {mtc-full} ({mtc-short}) web console.
1010

1111
[NOTE]
1212
====
@@ -27,14 +27,23 @@ The {mtc-short} web console must contain the following:
2727
.Procedure
2828

2929
. Log in to the {mtc-short} web console and click *Migration plans*.
30-
. 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.
30+
. Click the Options menu {kebab} next to a migration plan and select one of the following options under *Migration*:
31+
32+
* *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.
33+
34+
* *Cutover* stops the transactions on the source cluster and moves the resources to the target cluster.
35+
+
36+
Optional: In the *Cutover migration* dialog, you can clear the *Halt transactions on the source cluster during migration* checkbox.
37+
38+
* *State* copies selected persistent volume claims (PVCs) and Kubernetes resources that store an application's state.
3139
+
32-
You can run *Stage* multiple times to reduce the actual migration time.
40+
[IMPORTANT]
41+
====
42+
Do not use state migration to migrate a namespace.
43+
====
3344

34-
. When you are ready to migrate the application workload, the *Options* menu {kebab} beside a migration plan and select *Migrate*.
45+
** Select one or more PVCs in the *State migration* dialog and click *Migrate*.
3546

36-
. Optional: In the *Migrate* window, you can select *Do not stop applications on the source cluster during migration*.
37-
. Click *Migrate*.
3847
. When the migration is complete, verify that the application migrated successfully in the {product-title} web console:
3948

4049
.. Click *Home* -> *Projects*.

‎modules/migration-state-migration-cli.adoc‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * migrating_from_ocp_3_to_4/about-mtc-3-4.adoc
4+
// * migration_toolkit_for_containers/about-mtc.adoc
5+
6+
[id="migration-state-migration-cli_{context}"]
7+
= Migrating an application's state
8+
9+
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.
10+
11+
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}.
12+
13+
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.
14+
15+
You can perform a one-time migration of Kubernetes objects that store application state.
16+
17+
[id="excluding-pvcs_{context}"]
18+
== Excluding persistent volume claims
19+
20+
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.
21+
22+
.Prerequisites
23+
24+
* `MigPlan` CR with discovered PVs.
25+
26+
.Procedure
27+
28+
* Add the `spec.persistentVolumes.pvc.selection.action` parameter to the `MigPlan` CR and set its value to `skip`:
29+
+
30+
[source,yaml]
31+
----
32+
apiVersion: migration.openshift.io/v1alpha1
33+
kind: MigPlan
34+
metadata:
35+
name: <migplan>
36+
namespace: openshift-migration
37+
spec:
38+
...
39+
persistentVolumes:
40+
- capacity: 10Gi
41+
name: <pv_name>
42+
pvc:
43+
...
44+
selection:
45+
action: skip <1>
46+
----
47+
<1> `skip` excludes the PVC from the migration plan.
48+
49+
[id="mapping-pvcs_{context}"]
50+
== Mapping persistent volume claims
51+
52+
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.
53+
54+
.Prerequisites
55+
56+
* `MigPlan` CR with discovered PVs.
57+
58+
.Procedure
59+
60+
* Update the `spec.persistentVolumes.pvc.name` parameter in the `MigPlan` CR:
61+
+
62+
[source,yaml]
63+
----
64+
apiVersion: migration.openshift.io/v1alpha1
65+
kind: MigPlan
66+
metadata:
67+
name: <migplan>
68+
namespace: openshift-migration
69+
spec:
70+
...
71+
persistentVolumes:
72+
- capacity: 10Gi
73+
name: <pv_name>
74+
pvc:
75+
name: <source_pvc>:<destination_pvc> <1>
76+
----
77+
<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.
78+
79+
[id="migrating-kubernetes-objects_{context}"]
80+
== Migrating Kubernetes objects
81+
82+
You can perform a one-time migration of Kubernetes objects that store an application's state.
83+
84+
[NOTE]
85+
====
86+
After migration, the `closed` parameter of the `MigPlan` CR is set to `true`. You cannot create another `MigMigration` CR for this `MigPlan` CR.
87+
====
88+
89+
You add Kubernetes objects to the `MigPlan` CR by using the following options:
90+
91+
* Adding the Kubernetes objects to the `includedResources` section.
92+
* Using the `labelSelector` parameter to reference labeled Kubernetes objects.
93+
94+
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`.
95+
96+
.Procedure
97+
98+
* Update the `MigPlan` CR:
99+
+
100+
[source,yaml]
101+
----
102+
apiVersion: migration.openshift.io/v1alpha1
103+
kind: MigPlan
104+
metadata:
105+
name: <migplan>
106+
namespace: openshift-migration
107+
spec:
108+
includedResources: <1>
109+
- kind: <Secret>
110+
group: ""
111+
- kind: <ConfigMap>
112+
group: ""
113+
...
114+
labelSelector:
115+
matchLabels:
116+
<app: frontend> <2>
117+
----
118+
<1> Specify the `kind` and `group` of each resource.
119+
<2> Specify the label of the resources to migrate.

0 commit comments

Comments
 (0)