ImageTransport is a tool that can be used to migrate images from the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance in the same region. This topic describes how to use ImageTransport to migrate images from the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance.

Features of ImageTransport

ImageTransport is an image migration tool. It supports the following features:
  • Migrates images based on the memory. The memory-based migration is fast.
  • Allows you to specify namespace mappings.
    • You can specify the source namespaces in the Container Registry Personal Edition instance from which images are migrated to the Container Registry Enterprise Edition instance.
    • You can specify namespace mappings. For example, you can migrate images from Namespace A in the Container Registry Personal Edition instance to Namespace A in the Container Registry Enterprise Edition instance. You can also migrate images from Namespace A in the Container Registry Personal Edition instance to Namespace b in the Container Registry Enterprise Edition instance.
  • Obtains all namespaces of the Container Registry Personal Edition instance and checks whether the namespaces exist in the Container Registry Enterprise Edition instance.
    1. If a namespace does not exist, the corresponding namespace is created in the Container Registry Enterprise Edition instance and the automatic repository creation feature is enabled.
    2. If a namespace exists, check whether the automatic repository creation feature is enabled and make sure that the feature is enabled.
  • Obtains all the image repositories of the Container Registry Personal Edition instance and check whether the image repositories exist in the Container Registry Enterprise Edition instance.
    • If an image repository does not exist, the corresponding image repository with the same type and description is created in the Container Registry Enterprise Edition instance.
    • If an image repository exists, ImageTransport does not modify the settings of the image repository.
    • ImageTransport checks whether the source and destination image repositories have the same image build settings. If the settings are different, ImageTransport synchronizes the settings to the destination image repositories in the Container Registry Enterprise Edition instance.
  • ImageTransport supports three synchronization policies to migrate images in image repositories.
    • Full synchronization: All images are synchronized to the Container Registry Enterprise Edition instance at a time.
    • Batch synchronization: ImageTransport allows you to synchronize only a specific number of the latest images from each image repository.
    • Incremental synchronization: ImageTransport can synchronize multiple images each time and ignore the images that have been synchronized.
  • Allows you to view the synchronization progress of each synchronization task each time in real time.
    • ImageTransport counts the total number of images when it synchronizes images.
    • ImageTransport calculates the proportion of synchronized images in real time and estimates the completion time.

Usage notes

  • You can migrate images only from the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance in the same region.
  • The account used for migration must have the read-only permissions on the Container Registry Personal Edition instance and Container Registry Enterprise Edition instance. The password used to log on to the image repositories in the Container Registry Personal Edition instance is configured.
    Notice Assume that the namespaces and image repositories in the Container Registry Enterprise Edition instance are inconsistent with those in the Container Registry Personal Edition instance during image migration. Check whether the RAM authorization is valid and then whether permissions are granted in the Container Registry console. If permissions are granted in the Container Registry console, the system ignores the permissions that are granted by using Resource Access Management (RAM). For more information, see FAQ.

Before you begin

Prepare the environment before migration
  • Prepare an Elastic Compute Service (ECS) instance for migration

    Prepare an ECS instance in the same region as the Container Registry Enterprise Edition instance. We recommend that you use an ECS instance that has high specifications and high internal bandwidth.

  • Configure a Container Registry Enterprise Edition instance

    Configure the same virtual private cloud (VPC) for the ECS instance as that of the Container Registry Enterprise Edition instance. For more information, see Configure access over VPCs.

  • Prepare an account used for migration

    Prepare an account that has the read and write permissions on the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance. In addition, obtain the AccessKey ID and AccessKey secret of the account.

  • Prepare the logon names and passwords used to log on to image repositories

    Prepare the logon names and passwords used to log on to the image repositories of the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance. For more information, see Use a Container Registry Enterprise Edition instance to push and pull images.

  • Bind a source code repository

    If you want to synchronize image build settings, bind the same source code repository to the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance.

Prepare the information required for parameter settings
Parameter Example Required Description
instanceId cri-1234**** Yes The ID of the Container Registry Enterprise Edition instance. You can obtain the ID on the Overview page of the Container Registry Enterprise Edition instance.
accessKey ak-example Yes The AccessKey ID of the account that has the read and write permissions on the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance.
secretKey sk-example Yes The AccessKey secret of the account that has the read and write permissions on the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance.
regionId cn-hangzhou Yes The region where the Container Registry Personal Edition instance and the Container Registry Enterprise Edition instance reside.
auth4DefaultInstance default:default Yes The logon name and password that are used to log on to the image repositories of the Container Registry Personal Edition instance. Connect the logon name and password with a colon (:).
auth4EnterpriseInstance enterprise:enterprise Yes The logon name and password that are used to log on to the image repositories of the Container Registry Enterprise Edition instance. Connect the logon name and password with a colon (:).
namespace a,b:bb,c No The mappings between the source namespaces in the Container Registry Personal Edition instance and the destination namespaces in the Container Registry Enterprise Edition instance. If the destination namespace is not specified in a mapping, the namespace with the same name as the source namespace is mapped to the source namespace. Separate mappings with commas (,) and separate the source namespace and the mapped destination namespace with colons (:) in each mapping. For example, if the namespace parameter is set to a,b:bb,c, one of the following two situations occurs:
  • Assume that the Container Registry Enterprise Edition instance has Namespace a, Namespace bb, and Namespace c. ImageTransport migrates the images from Namespaces a and c in the Container Registry Personal Edition instance to Namespaces a and c in the Container Registry Enterprise Edition instance. ImageTransport also migrates the images from Namespace b in the Container Registry Personal Edition instance to Namespace bb in the Container Registry Enterprise Edition instance.
  • Assume that the Container Registry Enterprise Edition instance does not have Namespace a, Namespace bb, and Namespace c. The Container Registry Enterprise Edition instance automatically creates three namespaces and names them a, bb, and c. Then, ImageTransport migrates the images from Namespaces a and c in the Container Registry Personal Edition instance to Namespaces a and c in the Container Registry Enterprise Edition instance. ImageTransport also migrates the images from Namespace b in the Container Registry Personal Edition instance to Namespace bb in the Container Registry Enterprise Edition instance.
intranet true No Specifies whether to migrate images over the internal network. The default value is true, which indicates that images are migrated over the internal network.
tagNum 20 No The number of the latest images that you want to synchronize in each image repository. You can set the value to -1 or an integer from 1 to 100. The default value is -1, which indicates that all images are synchronized.

Scenario 1: Migrate all images over a VPC

You can migrate all images of the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance.

Run the following command to migrate images from the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance:
docker run -ti registry.cn-hangzhou.aliyuncs.com/acr-toolkit/image-transport:aliyun-0.0.3 image-transport \
    --accessKey ak-example \
    --secretKey sk-example \
    --instanceId cri-12345678 \
    --regionId cn-hangzhou \
    --auth4DefaultInstance default:default \
    --auth4EnterpriseInstance enterprise:enterprise
The synchronization progress is displayed in real time in the command output.
INFO[2021-01-07 12:45:36]   Synchronization progress report:
INFO[2021-01-07 12:45:36]   Total images: 103, Synced images: 33, Fail synced images: 0, Achieved ratio: 32.04%
INFO[2021-01-07 12:45:36]   Total data: 6883.2 MB, Synced data: 2782.9 MB, Achieved ratio: 40.43%
INFO[2021-01-07 12:45:36]   Average speed: 46.38 MB/s, Realtime speed: 46.38 MB/s
INFO[2021-01-07 12:45:36]   Time cost: 1m:0s, Estimate remaining time: 1m:28s, Estimate remaining time by realtime speed: 1m:28s

Scenario 2: Migrate a specific number of the latest images over a VPC

Assume that the total size of the images in the Container Registry Personal Edition instance is larger than a petabyte and you want to migrate only the latest images. You can migrate a specific number of the latest images from each repository.

Run the following command to migrate the latest 20 images from each repository of the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance:
docker run -ti registry.cn-hangzhou.aliyuncs.com/acr-toolkit/image-transport:aliyun-0.0.3 image-transport \
    --accessKey ak-example \
    --secretKey sk-example \
    --instanceId cri-12345678 \
    --regionId cn-hangzhou \
    --auth4DefaultInstance default:default \
    --auth4EnterpriseInstance enterprise:enterprise \
    --tagNum 20

Scenario 3: Migrate images that have not been migrated over a VPC

Assume that you have previously migrated the latest 20 images in each repository of the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance. If you want to migrate the latest 40 images from each repository of the Container Registry Personal Edition instance, you can set the tagNum parameter to 40. The system skips the 20 images that have been migrated and migrates the other 20 images.

Run the following command to migrate the latest 40 images from each repository of the Container Registry Personal Edition instance to a Container Registry Enterprise Edition instance:

docker run -ti registry.cn-hangzhou.aliyuncs.com/acr-toolkit/image-transport:aliyun-0.0.3 image-transport \
    --accessKey ak-example \
    --secretKey sk-example \
    --instanceId cri-12345678 \
    --regionId cn-hangzhou \
    --auth4DefaultInstance default:default \
    --auth4EnterpriseInstance enterprise:enterprise \
    --tagNum 40

Scenario 4: Specify namespace mappings

Assume that you want to migrate only the latest 20 images from each image repositories of Namespaces test-a and test-b in the Container Registry Personal Edition instance to Namespaces test-a and test-c in the Container Registry Enterprise Edition instance. You can set the tagNum parameter to 20 and set the namespace parameter to test-a,test-b:test-c.

Run the following command to specify namespace mappings and migrate only the latest 20 images in each repository:
docker run -ti registry.cn-hangzhou.aliyuncs.com/acr-toolkit/image-transport:aliyun-0.0.3 image-transport \
    --accessKey ak-example \
    --secretKey sk-example \
    --instanceId cri-12345678 \
    --regionId cn-hangzhou \
    --auth4DefaultInstance default:default \
    --auth4EnterpriseInstance enterprise:enterprise \
    --namespace test-a,test-b:test-c \
    --tagNum 20

FAQ

Why are the namespaces and image repositories in the Container Registry Enterprise Edition instance inconsistent with those in the Container Registry Personal Edition instance during image migration?

This issue occurs because the system ignores the permissions that are granted by using RAM when the permissions are granted in the Container Registry console. To resolve this issue, you can revoke the permissions that are granted in the Container Registry console and use RAM to grant permissions. You can also create a RAM user and grant the required permissions to the RAM user. To revoke the permissions that are granted in the Container Registry console, perform the following steps:

  1. Log on to the Container Registry console.
  2. In the top navigation bar, select a region.
  3. On the Instances page, click the default instance.
  4. On the management page of the Container Registry Personal Edition instance, choose Repositoires > Repositories. On the Repositories page, click the name of the image repository on which you want to revoke permissions.
  5. On the details page that appears, click Authorization in the left-side navigation pane. Find the permission that you want to revoke and click Delete in the Actions column.
  6. In the message that appears, click OK.