All Products
Search

This Product

    Container Service for Kubernetes:Install migrate-controller and grant permissions

    Document Center

    Container Service for Kubernetes:Install migrate-controller and grant permissions

    Last Updated:Apr 10, 2025

    The backup center enables application backup, recovery, and migration. You can use the backup center to implement disaster recovery and application migration in multi-cluster and hybrid environments. To use the backup center, you must install the migrate-controller component and configure related permissions to enable backup capabilities.

    Before you begin

    Background information

    As more applications run in Kubernetes, regular backups become increasingly important. The backup center can effectively prevent prolonged service interruptions caused by unexpected situations. Unlike traditional single-machine or disk backups, Kubernetes-based application backups primarily focus on applications running in Kubernetes and their data, resource objects, configurations, and entire namespaces.

    Notes

    • When you use the backup center feature with ACK Serverless cluster Pro Edition and ACK Edge cluster, the installation and permission configuration requirements are the same as those for ACK managed cluster. For more information, see ACK managed cluster.

      ACK Serverless cluster Basic Edition does not support the backup center feature.

    • ACK Serverless cluster Pro Edition and ACK Edge cluster do not support storage volume backup when you use the backup center feature.

    • The migrate-controller component of an ACK Edge cluster is installed on cloud nodes by default and accesses OSS through the internal network.

    ACK managed cluster

    Step 1: Install migrate-controller

    Note

    If you are using the backup center feature for the first time, you need to install the backup service component. If the component is already installed, you can skip this step.

    1. Log on to the ACK console. In the left-side navigation pane, click Clusters.

    2. On the Clusters page, find the cluster that you want to manage and click its name. In the left-side pane, choose Operations > Application Backup.

    3. On the Application Backup page, click Start Installation.

      The system automatically checks the backup repository. If no backup repository is created, see Create a backup repository.

      • After the backup service component is installed, a namespace named csdr is created. Do not delete this namespace.

      • If you have installed the component but it is not the latest version, click Application Backup and then click Start Upgrade. The system automatically upgrades the application backup service component to the latest version.

    Step 2: Grant related permissions

    • OSS permissions

      For an ACK managed cluster, we recommend that you use an OSS bucket whose name starts with cnfs-oss-*** as the backup repository for the backup center. In this case, you do not need to configure OSS permissions. If you use other buckets, you need to configure OSS permissions as described in ACK dedicated cluster. For more information, see Step 1: Configure related permissions.

    • Disk snapshot and Cloud Backup permissions

      For an ACK managed cluster, you do not need to configure disk snapshot and Cloud Backup permissions.

    (Optional) Step 3: Grant API Gateway permissions to Cloud Backup

    If you need to perform backup or restore tasks in a cluster in the China (Ulanqab), China (Heyuan), or China (Guangzhou) region, you need to use your Alibaba Cloud account to grant API Gateway permissions to Cloud Backup when you use the feature for the first time. Each Alibaba Cloud account needs to be authorized only once.

    Note

    Starting from version 1.8.4, the migrate-controller component supports using Cloud Backup for storage volume backup in clusters in the China (Ulanqab), China (Heyuan), or China (Guangzhou) region. Supported storage volume types include OSS, NAS, CPFS, local storage, and storage volumes in hybrid cloud scenarios.

    1. Log on to the Cloud Backup console.

    2. In the left-side navigation pane, choose Backup > Container Backup.

    3. In the top navigation bar, select the region where the cluster is located, which is China (Ulanqab), China (Heyuan), or China (Guangzhou).

    4. In the Cloud Backup Authorization dialog box, click Confirm Authorization.

    ACK dedicated cluster

    Step 1: Configure related permissions

    Important

    migrate-controller 1.7.7 and later versions support cross-region restoration of Alibaba Cloud disks. To use this feature, follow the custom policy template below to grant the original RAM user additional permissions for ECS disk snapshots.

    1. Create a RAM user. For more information, see Create a RAM user.

    2. Create the following custom policy. For more information, see Create a custom policy by using the policy editor.

      In the following policy script, oss:**** represents OSS permission policies, ecs:**** represents ECS disk snapshot permission policies, and hbr:**** represents Cloud Backup permission policies.

      Expand to view the custom policy

      {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:PutObject",
        "oss:GetObject",
        "oss:DeleteObject",
        "oss:GetBucket",
        "oss:ListObjects",
        "oss:ListBuckets",
        "oss:GetBucketStat"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSnapshot",
        "ecs:DeleteSnapshot",
        "ecs:DescribeSnapshotGroups",
        "ecs:CreateAutoSnapshotPolicy",
        "ecs:ApplyAutoSnapshotPolicy",
        "ecs:CancelAutoSnapshotPolicy",
        "ecs:DeleteAutoSnapshotPolicy",
        "ecs:DescribeAutoSnapshotPolicyEX",
        "ecs:ModifyAutoSnapshotPolicyEx",
        "ecs:DescribeSnapshots",
        "ecs:DescribeInstances",
        "ecs:CopySnapshot",
        "ecs:CreateSnapshotGroup",
        "ecs:DeleteSnapshotGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hbr:CreateVault",
        "hbr:CreateBackupJob",
        "hbr:DescribeVaults",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeRestoreJobs",
        "hbr:SearchHistoricalSnapshots",
        "hbr:CreateRestoreJob",
        "hbr:AddContainerCluster",
        "hbr:DescribeContainerCluster",
        "hbr:DescribeRestoreJobs2",
        "hbr:CancelBackupJob",
        "hbr:CancelRestoreJob"
      ],
      "Resource": "*"
    }
  ]
}

      The preceding policy grants permissions on all OSS buckets. If you need to specify read and write permissions for OSS, modify the policy according to the following example. Replace mybackups in the following policy script with your OSS bucket name. For more information about granular access control for OSS, see Use RAM to manage OSS permissions.

      Expand to view the custom policy

      {
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "oss:PutObject",
        "oss:GetObject",
        "oss:DeleteObject",
        "oss:GetBucket",
        "oss:ListObjects",
        "oss:ListBuckets",
        "oss:GetBucketStat"
      ],
      "Resource": [
        "acs:oss:*:*:mybackups",
        "acs:oss:*:*:mybackups/*"
      ],
      "Effect": "Allow"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSnapshot",
        "ecs:DeleteSnapshot",
        "ecs:DescribeSnapshotGroups",
        "ecs:CreateAutoSnapshotPolicy",
        "ecs:ApplyAutoSnapshotPolicy",
        "ecs:CancelAutoSnapshotPolicy",
        "ecs:DeleteAutoSnapshotPolicy",
        "ecs:DescribeAutoSnapshotPolicyEX",
        "ecs:ModifyAutoSnapshotPolicyEx",
        "ecs:DescribeSnapshots",
        "ecs:DescribeInstances",
        "ecs:CopySnapshot",
        "ecs:CreateSnapshotGroup",
        "ecs:DeleteSnapshotGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hbr:CreateVault",
        "hbr:CreateBackupJob",
        "hbr:DescribeVaults",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeRestoreJobs",
        "hbr:SearchHistoricalSnapshots",
        "hbr:CreateRestoreJob",
        "hbr:AddContainerCluster",
        "hbr:DescribeContainerCluster",
        "hbr:DescribeRestoreJobs2",
        "hbr:CancelBackupJob",
        "hbr:CancelRestoreJob"
      ],
      "Resource": "*"
    }
  ]
}

    3. Attach the preceding custom policy to the RAM user. For more information, see Grant permissions to a RAM user.

    4. Create an AccessKey pair for the RAM user. For more information, see Obtain an AccessKey pair.

    5. Create a Secret in the ACK dedicated cluster.

      To ensure that your AccessKey information is securely used only within your cluster, you need to first deploy a Secret resource named alibaba-addon-secret in the cluster using your AccessKey information to reduce the risk of leakage.

      1. Run the following command to create a namespace named csdr.

        kubectl create ns csdr

      2. Run the following command to create a Secret named alibaba-addon-secret:

        kubectl -n csdr create secret generic alibaba-addon-secret --from-literal='access-key-id=<your AccessKey ID>' --from-literal='access-key-secret=<your AccessKey Secret>'

        You need to replace <your AccessKey ID> and <your AccessKey Secret> in the preceding code with the AccessKey information that you obtained in the previous step.

        Note

        If you create a Secret after you install the migrate-controller component, restart the migrate-controller component in the kube-system namespace.

    Step 2: Install migrate-controller

    See Install migrate-controller.

    (Optional) Step 3: Grant API Gateway permissions to Cloud Backup

    Authorization is required only for backup or restore operations in clusters in the China (Ulanqab), China (Heyuan), or China (Guangzhou) region. For authorization operations, see (Optional) Step 3: Grant API Gateway permissions to Cloud Backup.

    Registered cluster

    Important

    migrate-controller 1.7.7 and later versions support cross-region restoration of Alibaba Cloud disks. Update onectl to version 1.1.0 and run the onectl ram-user revoke --addon migrate-controller command to grant additional permissions to the original RAM user.

    Use onectl to install migrate-controller and grant permissions (recommended)

    1. Install onectl on your on-premises machine. For more information, see Manage registered clusters by using onectl.

    2. Run the following command to grant RAM permissions to migrate-controller:

      onectl ram-user grant --addon migrate-controller

      Expected output:

      Ram policy ack-one-registered-cluster-policy-migrate-controller granted to ram user ack-one-user-ce313528c3 successfully.

    3. Run the following command to install migrate-controller:

      onectl addon install migrate-controller

      Expected output:

      Addon migrate-controller, version **** installed.

      The OSS permissions configured by onectl apply to all OSS buckets. If you need to configure permissions for specific OSS buckets, modify the OSS permissions generated by onectl or choose Manually install migrate-controller and grant permissions.

      Modify OSS Permissions: Modify the content of the created custom policy to the following. For information about how to modify a policy, see Modify the content and notes of a custom policy.

      Note

      Replace mybackups in the following policy with your OSS bucket name. For more information about granular access control for OSS, see Use RAM to manage OSS permissions.

      Expand to view the custom policy

      {
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "oss:PutObject",
        "oss:GetObject",
        "oss:DeleteObject",
        "oss:GetBucket",
        "oss:ListObjects",
        "oss:ListBuckets",
        "oss:GetBucketStat"
      ],
      "Resource": [
        "acs:oss:*:*:mybackups",
        "acs:oss:*:*:mybackups/*"
      ],
      "Effect": "Allow"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSnapshot",
        "ecs:DeleteSnapshot",
        "ecs:DescribeSnapshotGroups",
        "ecs:CreateAutoSnapshotPolicy",
        "ecs:ApplyAutoSnapshotPolicy",
        "ecs:CancelAutoSnapshotPolicy",
        "ecs:DeleteAutoSnapshotPolicy",
        "ecs:DescribeAutoSnapshotPolicyEX",
        "ecs:ModifyAutoSnapshotPolicyEx",
        "ecs:DescribeSnapshots",
        "ecs:DescribeInstances",
        "ecs:CopySnapshot",
        "ecs:CreateSnapshotGroup",
        "ecs:DeleteSnapshotGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hbr:CreateVault",
        "hbr:CreateBackupJob",
        "hbr:DescribeVaults",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeRestoreJobs",
        "hbr:SearchHistoricalSnapshots",
        "hbr:CreateRestoreJob",
        "hbr:AddContainerCluster",
        "hbr:DescribeContainerCluster",
        "hbr:DescribeRestoreJobs2",
        "hbr:CancelBackupJob",
        "hbr:CancelRestoreJob"
      ],
      "Resource": "*"
    }
  ]
}

    4. (Optional) Create routes that point to the internal network of the region where the registered cluster and OSS bucket reside.

      If the registered cluster is connected to a virtual private cloud (VPC) through Cloud Enterprise Network (CEN), Express Connect, or VPN and the registered cluster resides in the region of the OSS bucket, the backup center accesses the internal endpoint of the OSS bucket by default to increase the download speeds. Therefore, you need to create routes that point to the internal network of the region where the OSS bucket resides.

    5. (Optional) Grant API Gateway permissions to Cloud Backup.

      Authorization is required only for backup or restore operations in clusters in the China (Ulanqab), China (Heyuan), or China (Guangzhou) region. For authorization operations, see (Optional) Step 3: Grant API Gateway permissions to Cloud Backup.

    Use the console to install migrate-controller and grant permissions

    Step 1: Configure related permissions

    You need to create a RAM user for the registered cluster, grant the RAM user the permissions to access cloud resources, and then create an AccessKey pair for the RAM user.

    1. Create a RAM user. For more information, see Create a RAM user.

    2. Create the following custom policy. For more information, see Create a custom policy by using the policy editor.

      In the following policy script, oss:**** represents OSS permission policies, ecs:**** represents ECS disk snapshot permission policies, and hbr:**** represents Cloud Backup permission policies.

      Expand to view the custom policy

      {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "oss:PutObject",
        "oss:GetObject",
        "oss:DeleteObject",
        "oss:GetBucket",
        "oss:ListObjects",
        "oss:ListBuckets",
        "oss:GetBucketStat"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSnapshot",
        "ecs:DeleteSnapshot",
        "ecs:DescribeSnapshotGroups",
        "ecs:CreateAutoSnapshotPolicy",
        "ecs:ApplyAutoSnapshotPolicy",
        "ecs:CancelAutoSnapshotPolicy",
        "ecs:DeleteAutoSnapshotPolicy",
        "ecs:DescribeAutoSnapshotPolicyEX",
        "ecs:ModifyAutoSnapshotPolicyEx",
        "ecs:DescribeSnapshots",
        "ecs:DescribeInstances",
        "ecs:CopySnapshot",
        "ecs:CreateSnapshotGroup",
        "ecs:DeleteSnapshotGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hbr:CreateVault",
        "hbr:CreateBackupJob",
        "hbr:DescribeVaults",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeRestoreJobs",
        "hbr:SearchHistoricalSnapshots",
        "hbr:CreateRestoreJob",
        "hbr:AddContainerCluster",
        "hbr:DescribeContainerCluster",
        "hbr:DescribeRestoreJobs2",
        "hbr:CancelBackupJob",
        "hbr:CancelRestoreJob"
      ],
      "Resource": "*"
    }
  ]
}

      The preceding policy grants permissions on all OSS buckets. If you need to specify read and write permissions for OSS, modify the policy according to the following example. Replace mybackups in the following policy script with your OSS bucket name. For more information about granular access control for OSS, see Use RAM to manage OSS permissions.

      Expand to view the custom policy

      {
  "Version": "1",
  "Statement": [
    {
      "Action": [
        "oss:PutObject",
        "oss:GetObject",
        "oss:DeleteObject",
        "oss:GetBucket",
        "oss:ListObjects",
        "oss:ListBuckets",
        "oss:GetBucketStat"
      ],
      "Resource": [
        "acs:oss:*:*:mybackups",
        "acs:oss:*:*:mybackups/*"
      ],
      "Effect": "Allow"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ecs:CreateSnapshot",
        "ecs:DeleteSnapshot",
        "ecs:DescribeSnapshotGroups",
        "ecs:CreateAutoSnapshotPolicy",
        "ecs:ApplyAutoSnapshotPolicy",
        "ecs:CancelAutoSnapshotPolicy",
        "ecs:DeleteAutoSnapshotPolicy",
        "ecs:DescribeAutoSnapshotPolicyEX",
        "ecs:ModifyAutoSnapshotPolicyEx",
        "ecs:DescribeSnapshots",
        "ecs:DescribeInstances",
        "ecs:CopySnapshot",
        "ecs:CreateSnapshotGroup",
        "ecs:DeleteSnapshotGroup"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hbr:CreateVault",
        "hbr:CreateBackupJob",
        "hbr:DescribeVaults",
        "hbr:DescribeBackupJobs2",
        "hbr:DescribeRestoreJobs",
        "hbr:SearchHistoricalSnapshots",
        "hbr:CreateRestoreJob",
        "hbr:AddContainerCluster",
        "hbr:DescribeContainerCluster",
        "hbr:DescribeRestoreJobs2",
        "hbr:CancelBackupJob",
        "hbr:CancelRestoreJob"
      ],
      "Resource": "*"
    }
  ]
}

    3. Attach the custom policy to the RAM user. For more information, see Grant permissions to a RAM user.

    4. Create an AccessKey pair for the RAM user. For more information, see Obtain an AccessKey pair.

    5. Create a Secret in the cluster.

      To ensure that your AccessKey information is securely used only within your cluster, you need to first deploy a Secret resource named alibaba-addon-secret in the cluster using your AccessKey information to reduce the risk of leakage.

      1. Run the following command to create a namespace named csdr.

        kubectl create ns csdr

      2. Run the following command to create a Secret named alibaba-addon-secret:

        kubectl -n csdr create secret generic alibaba-addon-secret --from-literal='access-key-id=<your AccessKey ID>' --from-literal='access-key-secret=<your AccessKey Secret>'

        You need to replace <your AccessKey ID> and <your AccessKey Secret> in the preceding code with the AccessKey information that you obtained in the previous step.

    Step 2: Install migrate-controller

    See Install migrate-controller.

    (Optional) Step 3: Create routes that point to the internal network of the region where the registered cluster and OSS bucket reside

    If the registered cluster is connected to a VPC through CEN, Express Connect, or VPN and the registered cluster resides in the region of the OSS bucket, the backup center accesses the internal endpoint of the OSS bucket by default to increase the download speeds. Therefore, you need to create routes that point to the internal network of the region where the OSS bucket resides.

    (Optional) Step 4: Grant API Gateway permissions to Cloud Backup

    Authorization is required only for backup or restore operations in clusters in the China (Ulanqab), China (Heyuan), or China (Guangzhou) region. For authorization operations, see (Optional) Step 3: Grant API Gateway permissions to Cloud Backup.