Skip to main content
Version: 3.2

Migration with Stork

This document will guide you through the process of migrating your Portworx volumes one time between clusters using Stork. If you wish to set up disaster recovery, refer to the Disaster Recovery section.

Prerequisites​

  • Secret Store: A secret store is configured on both clusters. This will store the credentials for the objectstore.
  • Objectstore: An AWS S3 compatible, AWS S3, GCP Object Storage, or Azure Blob Storage.
  • Network Connectivity:
    • Kubernetes: All worker nodes are able to reach Kubernetes API endpoints on both Kubernetes clusters, for example, port 6443, 443 and so on.
    • Portworx: Open port in the range of 9001-9020 for Portworx worker nodes to communicate with each other. To know more about the specific ports for your environment, see the Network table on the Prerequisites page.
  • Default StorageClass: At most one StorageClass object is configured as the default. Having multiple default StorageClasses will cause PVC migrations to fail.
  • Cloud Environment: Depending on your cloud provider (EKS, GKE, AAD enabled AKS, or OKE) ensure that you have successfully applied the instructions provided on the respective page for setting up your destination cluster.
  • storkctl is installed on both clusters. Note that always use the latest storkctl binary tool by downloading it from the current running Stork container.

note

The default admin namespace is kube-system. In all examples, <migrationnamespace> is considered the admin namespace responsible for migrating all namespaces from your source cluster to the destination cluster. Alternatively, you can specify a non-admin namespace, in such a case, only that specific namespace will be migrated. To learn how to set up an admin namespace, refer to the Set up a Cluster Admin namespace for Migration page.

Create a ClusterPair object​

For migration with Stork, it is essential to pair two clusters to enable the migration of data and resources. To facilitate this process, you need to create a trust object, known as ClusterPair object, on the source cluster. Portworx requires this object to establish a communication channel between the two clusters.

The ClusterPair object pairs the two clusters, allowing migration of resources and volumes.

Pair your clusters​

Use the storkctl create clusterpair command to create your unidirectional ClusterPair using the command options specific to your environment, as explained in the following sections. The unidirectional ClusterPair will establish authentication from the source cluster to the destination cluster so resources and data can be migrated in one direction.​​

This command creates Clusterpair object on the source cluster using the source config file (<source-kubeconfig-cluster>) and the destination kubeconfig file (<destination-kubeconfig-cluster>) in the specified namespace (<migrationnamespace>). This object establishes and authenticates the connection between the two clusters for migrating resources and volumes within the specified namespace.

note

If you configured the portworx-api service to be accessible externally through ingresses or routes, specify the following two additional command options while creating the ClusterPair:

  • --dest-ep string: Endpoint of the portworx-api service in the destination cluster.
  • --src-ep string: Endpoint of the portworx-api service in the source cluster.

If the above endpoints are not specified, the storage status of the ClusterPair will show as failed.

Create a unidirectional ClusterPair​

Depending upon your ObjectStore, click the appropriate tab to run the command to create a unidirectional ClusterPair named migration-cluster-pair for cluster migration:

Run the following command to create a unidirectional ClusterPair named migration-cluster-pair for cluster migration:

storkctl create clusterpair migration-cluster-pair \
--namespace <migrationnamespace> \
--dest-kube-file <destination-kubeconfig-file> \
--src-kube-file <source-kubeconfig-file> \
--provider s3 \
--s3-endpoint s3.amazonaws.com \
--s3-access-key <s3-access-key> \
--s3-secret-key <s3-secret-key> \
--s3-region <s3-region> \
--mode migration \
--unidirectional

Portworx will use AWS S3 or S3 compatible blob storage for migrating volume data between the two clusters. The credentials specified in the above command are used for authenticating with the your cloud platform. The S3 bucket information is provided with the specified access key, secret key, and region (<s3-bucket-location>) to facilitate the data transfer between the two clusters.

​

Verify the status of your unidirectional ClusterPair​

​ The following command uses storkctl to retrieve information about the cluster pairs in the Kubernetes namespace <migrationnamespace>: ​

storkctl get clusterpair -n <migrationnamespace>

​ This command displays details such as the name and status of the existing cluster pairs within that specific namespace.

Source cluster details:

NAME                     STORAGE-STATUS  SCHEDULER-STATUS  CREATED
migration-cluster-pair   Ready           Ready             10 Mar 23 17:16 PST

​On a successful pairing, you should see the STORAGE-STATUS and SCHEDULER-STATUS as Ready.

Encountered an error?
If you see an error, you can get more information by running the following command:

oc describe clusterpair <your-clusterpair-name> -n <migrationnamespace>

Use Rancher Projects with ClusterPair​

Follow the instructions on the Use Rancher Projects with ClusterPair page if you are using Rancher projects, otherwise skip to the next section.

Start your migration​

Once the pairing is configured, applications can be migrated repeatedly to the destination cluster.

You can either use the storkctl create migration command or create a migration object and apply it manually to start the migration.

Use the storkctl create migration command with the required flags. For more information, refer to storkctl create migration.

Example:

storkctl create migration <your-migration-object-name> \
  --clusterPair migration-cluster-pair \
  --namespaces <app-namespace1>,<app-namespace2> \
  --includeResources=true \
  --startApplications=true \
  --namespace <migrationNamespace>

Preview resources before starting migration​

To validate which resources will be included in a migration before creating it, use the --preview or --previewFile flags with the storkctl create migration command:

  • Use --preview to display the resources that will be included in the migration without initiating it.
  • Use --previewFile <filename> to save the preview output to a file.

This helps confirm which resources will be migrated before execution, including non-namespaced resources such as ClusterRole and ClusterRoleBinding.

Monitoring a migration​

Once the migration has been started using the previous commands, you can check the status using storkctl:

storkctl get migration -n <migrationnamespace>

Here is an example output that you will see initially when the migration is triggered:

NAME                                            CLUSTERPAIR              STAGE     STATUS       VOLUMES   RESOURCES   CREATED
<your-migration-object-name>-2022-12-12-200210  migration-cluster-pair   Volumes   InProgress   0/3       0/0         12 Dec 22 11:45 PST

If the migration is successful, the STAGE will change from Volumes to Application to Final.

Here is an example output of a successful migration:

NAME                                             CLUSTERPAIR            STAGE   STATUS       VOLUMES   RESOURCES   CREATED               ELAPSED
<your-migration-object-name>-2022-12-12-200210   migration-cluster-pair Final   Successful   3/3       10/10       12 Dec 22 12:02 PST   1m23s
Need to see more details?
If you see an error, or you want to see more details of your migration, run the following command:

kubectl describe clusterpair <your-clusterpair-name> -n <migrationnamespace>
Last updated on