Chapter 1. About the Migration Toolkit for Containers
The Migration Toolkit for Containers (MTC enables you to migrate stateful application workloads between OpenShift Container Platform 4 clusters at the granularity of a namespace.
If you are migrating from OpenShift Container Platform 3, see About migrating from OpenShift Container Platform 3 to 4 and Installing the legacy Migration Toolkit for Containers Operator on OpenShift Container Platform 3.
You can migrate applications within the same cluster or between clusters by using state migration.
MTC provides a web console and an API, based on Kubernetes custom resources, to help you control the migration and minimize application downtime.
The MTC console is installed on the target cluster by default. You can configure the Migration Toolkit for Containers Operator to install the console on a remote cluster.
See Advanced migration options for information about the following topics:
- Automating your migration with migration hooks and the MTC API.
- Configuring your migration plan to exclude resources, support large-scale migrations, and enable automatic PV resizing for direct volume migration.
1.1. Terminology
| Term | Definition |
|---|---|
| Source cluster | Cluster from which the applications are migrated. |
| Destination cluster[1] | Cluster to which the applications are migrated. |
| Replication repository | Object storage used for copying images, volumes, and Kubernetes objects during indirect migration or for Kubernetes objects during direct volume migration or direct image migration. The replication repository must be accessible to all clusters. |
| Host cluster |
Cluster on which the The host cluster does not require an exposed registry route for direct image migration. |
| Remote cluster | A remote cluster is usually the source cluster but this is not required.
A remote cluster requires a A remote cluster requires an exposed secure registry route for direct image migration. |
| Indirect migration | Images, volumes, and Kubernetes objects are copied from the source cluster to the replication repository and then from the replication repository to the destination cluster. |
| Direct volume migration | Persistent volumes are copied directly from the source cluster to the destination cluster. |
| Direct image migration | Images are copied directly from the source cluster to the destination cluster. |
| Stage migration | Data is copied to the destination cluster without stopping the application. Running a stage migration multiple times reduces the duration of the cutover migration. |
| Cutover migration | The application is stopped on the source cluster and its resources are migrated to the destination cluster. |
| State migration | Application state is migrated by copying specific persistent volume claims to the destination cluster. |
| Rollback migration | Rollback migration rolls back a completed migration. |
1 Called the target cluster in the MTC web console.
1.2. MTC workflow
You can migrate Kubernetes resources, persistent volume data, and internal container images to OpenShift Container Platform 4.10 by using the Migration Toolkit for Containers (MTC) web console or the Kubernetes API.
MTC migrates the following resources:
- A namespace specified in a migration plan.
Namespace-scoped resources: When the MTC migrates a namespace, it migrates all the objects and resources associated with that namespace, such as services or pods. Additionally, if a resource that exists in the namespace but not at the cluster level depends on a resource that exists at the cluster level, the MTC migrates both resources.
For example, a security context constraint (SCC) is a resource that exists at the cluster level and a service account (SA) is a resource that exists at the namespace level. If an SA exists in a namespace that the MTC migrates, the MTC automatically locates any SCCs that are linked to the SA and also migrates those SCCs. Similarly, the MTC migrates persistent volumes that are linked to the persistent volume claims of the namespace.
NoteCluster-scoped resources might have to be migrated manually, depending on the resource.
- Custom resources (CRs) and custom resource definitions (CRDs): MTC automatically migrates CRs and CRDs at the namespace level.
Migrating an application with the MTC web console involves the following steps:
Install the Migration Toolkit for Containers Operator on all clusters.
You can install the Migration Toolkit for Containers Operator in a restricted environment with limited or no internet access. The source and target clusters must have network access to each other and to a mirror registry.
Configure the replication repository, an intermediate object storage that MTC uses to migrate data.
The source and target clusters must have network access to the replication repository during migration. If you are using a proxy server, you must configure it to allow network traffic between the replication repository and the clusters.
- Add the source cluster to the MTC web console.
- Add the replication repository to the MTC web console.
Create a migration plan, with one of the following data migration options:
Copy: MTC copies the data from the source cluster to the replication repository, and from the replication repository to the target cluster.
NoteIf you are using direct image migration or direct volume migration, the images or volumes are copied directly from the source cluster to the target cluster.
Move: MTC unmounts a remote volume, for example, NFS, from the source cluster, creates a PV resource on the target cluster pointing to the remote volume, and then mounts the remote volume on the target cluster. Applications running on the target cluster use the same remote volume that the source cluster was using. The remote volume must be accessible to the source and target clusters.
NoteAlthough the replication repository does not appear in this diagram, it is required for migration.
Run the migration plan, with one of the following options:
Stage copies data to the target cluster without stopping the application.
A stage migration can be run multiple times so that most of the data is copied to the target before migration. Running one or more stage migrations reduces the duration of the cutover migration.
Cutover stops the application on the source cluster and moves the resources to the target cluster.
Optional: You can clear the Halt transactions on the source cluster during migration checkbox.
1.3. About data copy methods
The Migration Toolkit for Containers (MTC) supports the file system and snapshot data copy methods for migrating data from the source cluster to the target cluster. You can select a method that is suited for your environment and is supported by your storage provider.
1.3.1. File system copy method
MTC copies data files from the source cluster to the replication repository, and from there to the target cluster.
The file system copy method uses Restic for indirect migration or Rsync for direct volume migration.
| Benefits | Limitations |
|---|---|
|
|
The Restic and Rsync PV migration assumes that the PVs supported are only volumeMode=filesystem. Using volumeMode=Block for file system migration is not supported.
1.3.2. Snapshot copy method
MTC copies a snapshot of the source cluster data to the replication repository of a cloud provider. The data is restored on the target cluster.
The snapshot copy method can be used with Amazon Web Services, Google Cloud Provider, and Microsoft Azure.
| Benefits | Limitations |
|---|---|
|
|
1.4. Direct volume migration and direct image migration
You can use direct image migration (DIM) and direct volume migration (DVM) to migrate images and data directly from the source cluster to the target cluster.
If you run DVM with nodes that are in different availability zones, the migration might fail because the migrated pods cannot access the persistent volume claim.
DIM and DVM have significant performance benefits because the intermediate steps of backing up files from the source cluster to the replication repository and restoring files from the replication repository to the target cluster are skipped. The data is transferred with Rsync.
DIM and DVM have additional prerequisites.
