Container Service for Kubernetes:Migrate stateful applications with cloud disks across zones

Use cases

NAS and OSS support cross-zone and multi-mount. Disks are zone-bound — they cannot float across zones or reuse existing persistent volume claims (PVCs) and persistent volumes (PVs). Create new disks in the target zone from snapshots.

Key constraints

Review these constraints before migration:

• Business interruption required: To ensure data consistency, migration scales the StatefulSet to 0 replicas, then restores all at once after disk migration — not a rolling update. Plan for downtime. Duration depends on replica count, container startup time, and disk capacity.

• ESSD disks required: All storage used by the StatefulSet must be ESSD disks. Migration uses instant access snapshots, which only support ESSD disks.

• Target zone requirements: The target zone must support ESSD disks, and the cluster must have nodes in that zone available for scheduling.

If your application uses non-ESSD disks, do one of the following before migrating:

• Change the disk type to ESSD.

• Manually create a snapshot for a single disk volume and rebuild the disk across zones.

How it works

Cross-zone migration creates snapshots of source disks and uses instant access to minimize creation time. See Snapshot billing.

storage-operator runs these steps:

1. Precheck: Verifies the application is running and identifies disks to migrate. Stops if precheck fails.

2. Scale to zero: Scales the StatefulSet to 0 replicas, pausing the application.

3. Create snapshots: Creates instant access snapshots for all mounted disks. Snapshots are zone-agnostic.

4. Provision new disks: After confirming snapshots are available, creates new disks in the target zone with the same data.

5. Rebuild PVCs and PVs: Rebuilds PVCs with the same names and their corresponding PVs, bound to the new disks.

6. Restore replicas: Restores the original replica count. Replicas bind to rebuilt PVCs and mount the new disks.

7. (Optional) Delete original resources: After confirming application health, delete the original PVs and disks. See Block storage billing.

Prerequisites

Ensure the following:

• A cluster running Kubernetes 1.20 or later with the Container Storage Interface (CSI) driver installed

• storage-operator v1.26.2-1de13b6-aliyun or later installed

• csi-plugin and csi-provisioner installed, with csi-provisioner using the non-managed version

  If the managed version is installed, switch to non-managed. Then restart the storage controller: kubectl delete pod -n kube-system <storage-controller-pod-name>

• (ACK dedicated clusters only) Worker and master RAM roles have ModifyDiskSpec permission on the ECS API. See Create a custom policy. View the required RAM policy:

  ACK managed clusters do not require ModifyDiskSpec permission.

  {
      "Version": "1",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": [
                  "ecs:CreateSnapshot",
                  "ecs:DescribeSnapshot",
                  "ecs:DeleteSnapshot",
                  "ecs:ModifyDiskSpec",
                  "ecs:DescribeTaskAttribute"
              ],
              "Resource": "*"
          }
      ]
  }

  </details>

Migrate a StatefulSet across zones

kubectl patch configmap/storage-operator \
  -n kube-system \
  --type merge \
  -p '{"data":{"storage-controller":"{\"imageRep\":\"acs/storage-controller\",\"imageTag\":\"\",\"install\":\"true\",\"template\":\"/acs/templates/storage-controller/install.yaml\",\"type\":\"deployment\"}"}}'

cat <<EOF | kubectl apply -f -
apiVersion: storage.alibabacloud.com/v1beta1
kind: ContainerStorageOperator
metadata:
  name: default
spec:
  operationType: APPMIGRATE
  operationParams:
    stsName: web
    stsNamespace: default
    stsType: kube
    targetZone: cn-beijing-h,cn-beijing-j
    checkWaitingMinutes: "1"
    healthDurationMinutes: "1"
    snapshotRetentionDays: "2"
    retainSourcePV: "true"
EOF

Examples

The following examples use an ACK Pro cluster with nodes in three zones:

• Zone B: cn-shanghai.192.168.5.245

• Zone G: cn-shanghai.192.168.2.214

• Zone M: cn-shanghai.192.168.3.236, cn-shanghai.192.168.3.237

FAQ

If a migration task returns FAILED, get the error message:

kubectl describe cso <ContainerStorageOperator-name> | grep Message -A 1

Example output:

  Message:
    Consume: failed to get target pvc, err: no pvc mounted in statefulset or no pvc need to migrated web

The component could not find a PVC to migrate. Common causes:

• The StatefulSet has no mounted storage.

• All disks are already in the target zone — no migration is needed.

• The component could not retrieve PVC information.

Resolve the issue based on the error message, then reapply the migration task.