Scenario
Tencent Container Registry (TCR) currently offers both Individual and Enterprise Editions. The Individual Edition is designed for individual developers and provides only basic features for container image storage and distribution. The Enterprise Edition is tailored for enterprise users, offering secure, dedicated, and high-performance cloud-native artifacts hosting and distribution services. For the differences between the two editions, see Specification.
This document describes how enterprise customers can migrate container image data and business configuration from the Personal Edition to the Enterprise Edition to achieve smooth business migration.
Preparations
To migrate from the Personal Edition service to the Enterprise Edition, you need to confirm and complete the following preparations:
You have activated and used the Personal Edition service, and the migration operation account has the permission to pull all images from the Personal Edition image repository. Please refer to Personal Edition Authorization Scheme Example to grant full management permissions for the Personal Edition to the sub-account in advance.
You have purchased an Enterprise Edition instance, and the account used for migration has the permission to push images to the instance. Please refer to Enterprise Edition Authorization Solution Example to grant the sub-account the necessary permissions for container images and Helm Chart push in advance. It is recommended to grant full read and write permissions for the container image service to the sub-account used for configuration synchronization.
A suitable environment for running the migration tool has been set up. It is recommended to perform the migration task within a Virtual Private Cloud (VPC) to improve migration speed and avoid public network traffic costs.
Run the migration tool within the VPC: Add the private network where the migration tool server is located to the private network access of the target Enterprise Edition instance. For more information, see Private Network Access Control.
Run the migration tool in a public network environment: Enable the public network access entry for the target Enterprise Edition instance and allow access from the source. For more information, see Public Network Access Control.
Data Migration
Preparing the basic running environment
1. Purchase an Enterprise Edition instance in the region where the container business is deployed.
2. Prepare a Cloud Virtual Machine (CVM) in the same region for image migration, and preferably choose a model with high CPU/memory configuration and high internal network bandwidth. After the CVM starts, install the latest Docker client or choose an operating system with Docker pre-installed.
3. Connect the VPC where the CVM is located to the Enterprise Edition instance and enable automatic private network resolution. For more information, see Private Network Access Control.
4. Obtain the access credential for the instance and execute
Docker Login on the dedicated migration CVM. Ensure that the instance can be accessed and logged in successfully via the internal network on this CVM.Preparing migration configuration
1. Obtain the access credential of the image repository.
Personal Edition image repository access credentials: The username is the Tencent Cloud UIN of the account to which the image to be migrated belongs, and the password is the one set when initializing the Personal Edition service. If you have forgotten the password, you can go to TCR Console > Instance List, select the Personal Edition instance, and click Reset Login Password in the More menu to reset the password.
Enterprise Edition image repository access credential: Go to the TCR console > Access credential, select the created Enterprise Edition instance, click New to generate a long-term access credential for migration, which includes the username and password. Please note that the user generating this access credential must have full read and write permissions for the instance.
2. Obtain API credentials
During the image migration process, namespaces and image repositories will be automatically created within the Enterprise Edition instance, requiring Tencent Cloud API calls to complete the operation. You can go to **Access Management Console** > Access Keys > API Key Management to create a new key or view existing keys. Please handle this key information with care.
Downloading and running the migration tool
Run the following command to download the dedicated container image for migration:
docker pull ccr.ccs.tencentyun.com/tcrimages/image-transfer:ccr2tcr
Run the following command to view the instructions of the tool:
docker run --network=host --rm ccr.ccs.tencentyun.com/tcrimages/image-transfer:ccr2tcr /run --help
Run the following command to modify the configuration and execute the migration task:
docker run --network=host --rm ccr.ccs.tencentyun.com/tcrimages/image-transfer:ccr2tcr /run --tcrName image-transfer --ccrRegionName ap-guangzhou --tcrRegionName ap-shanghai --ccrAuth username:password --tcrAuth username:password --ccrSecretId sid- example --ccrSecretKey skey-example --tcrSecretId sid-example --tcrSecretKey skey-example --tagNum 50
Description
Category | Description |
tcrName | Name of the target Enterprise Edition instance |
ccrRegionName, ccrRegionName | Region of the instance. In the Chinese mainland, the CCR instance region defaults to ap-guangzhou, and the TCR instance region must be set to the actual region such as ap-shanghai. |
ccrAuth, tcrAuth | Access credential of the image repository in the format of username:password. If the username and password contain special characters, the special characters need to be escaped. For example, "?" should be written as "\?". |
ccrSecretId, ccrSecretKey, tcrSecretId, tcrSecretKey | Tencent Cloud API calling key. If the migration is under the same account, the calling keys of CCR and TCR are the same. |
tagNum | Specifies that only the latest N tags of images in the image repository will be migrated. |
Viewing and confirming the running result
Since the migration from Personal Edition to Enterprise Edition uses the full migration mode by default, the migration time is directly related to the number and size of the image repositories in the Personal Edition. Please be patient.
If the following code is displayed after running, it indicates that the full migration was successful. Otherwise, please rerun the migration tool to retry. You can request assistance through Online Consultation.
################# Finished, 0 transfer jobs failed, 0 normal urlPair generate failed, 0 jobs generate failed #################
Business Migration
Switching the network environment
The Personal Edition of Tencent Container Registry (TCR) does not have network access control features, and servers within the domestic region can access the service by default through the private network. The Enterprise Edition of TCR supports network access control, requiring the VPC where the cluster is located to be connected to the instance, allowing private network access.
Network configuration of the Personal Edition instance: no configuration is required. By default, you can access the instance and upload/download images via all network environments.
Network configuration of the Enterprise Edition instance:
Private Network Access (Recommended): Actively connect the VPC where the cluster or elastic cluster is located to the target instance, and enable automatic parsing within the VPC or manage DNS parsing yourself. For more information, see Private Network Access Control.
Public network access: we recommend that you enable the public network access only when testing or distributing images for the external teams, and the access allowlist must be configured.
Reusing the TCR Individual image configuration
Refer to the sub-document: Accessing Enterprise Edition Instances with Personal Edition Domain Names. By using this feature, you won't need to change the existing image repository addresses and access credential configurations in TKE clusters and CI/CD platforms, making it convenient for customers to switch to the Enterprise Edition service with minimal cost.
For long-term use, it is recommended to gradually switch the TCR Individual access configuration to the TCR Enterprise configuration to avoid access exceptions caused by subsequent changes in the TCR Individual service.
Using TCR Enterprise image configuration
Switching the access address
Navigate to the details page of the cluster or elastic cluster, select "Workload" on the left, and choose to create/update a workload. In "Instance Container", select or enter the image address, or directly modify the image parameter in the YAML file.
Personal Edition address: The default is
ccr.ccs.tencentyun.com/namespace/repo:tag. The default service region covers all available domestic regions except Hong Kong, China, such as Beijing, Shanghai, Guangzhou, etc. The prefix domain name for Hong Kong, China is hkccr. Multi-level paths are not supported.Enterprise Edition address: You can customize the instance name
user-define, for example, user-define.tencentcloudcr.com/namespace/repo:tag. Custom domain names are supported, such as xxx-company.com/namespace/repo:tag. Multi-level paths are supported, and the image address can be xxx-company.com/ns/sub01/sub02/repo:tag.Switching the access credential
Navigate to the cluster or elastic cluster details page, select "Workloads" on the left, and choose to create/update a workload. In "Image Access Credential", switch the access credential or directly modify the imagePullSecret parameter in the YAML file.
Personal Edition Access Credential: When creating a new namespace, the Personal Edition access credential, qcloudregistrykey, will be issued by default. Select this credential to proceed.
Access credential of Enterprise Edition instance:
Recommended Solution: Use the TCR Enterprise Edition dedicated plugin to automatically distribute and configure access credentials, enabling secret-free image pulling. This solution does not require configuring image access credentials; please delete any existing values for this parameter and keep it empty. (Supported only in TKE)
Manual configuration: you can configure a long-term access credential in the TCR Enterprise Edition instance, and deliver it to the namespace, or create the image access credential when creating the workload.
Best Practices for TCR Enterprise Instance
This document provides some best practices for migration from the Personal Edition to the Enterprise Edition.
Multi-instance planning
Based on your actual business needs, you can create one or more instances in multiple regions, configure synchronization and replication policies, and use custom domain names to manage instance access addresses uniformly. For more information, refer to TCR Enterprise Edition Instance Synchronization, TCR Enterprise Edition Instance Replication, and Synchronizing Images from Self-built Harbor to TCR Enterprise Edition.
Security and Compliance
Operation compliance
It is recommended to grant the minimum permissions to sub-accounts using the Enterprise Edition. Repository-level permission configuration is supported, allowing specific sub-accounts to pull/manage designated image repositories or even finer-grained API call permissions. For more information, see Example of Authorization Solution of TCR Enterprise.
You can create dedicated long-term access credentials for different usage scenarios. All long-term access credentials created by an account are only used for accessing the instance.
For temporary access to instances, it is recommended to use a temporary access credential (valid for 1 hour). For more information, see Obtaining a Temporary Login Token.
Network Security
Please do not enable the public network access entry to prevent the external unauthorized objects from accessing the instance, or avoid incurring public network access fees for downloading the images of your business via the public network.
You can bind a custom domain name to the instance, and manage the public network and VPC resolution of the domain name.
Image Management
Repository planning
We recommend that you use the namespace to isolate the services, teams, etc., to facilitate permission management and synchronization rule configuration.
Multi-level paths are supported. You can create multi-level repositories as needed to avoid creating too many namespaces.
You can push images to automatically create the repositories, and configure the default attributes such as public/private at the namespace level.
Please note: Namespaces, image repositories, and other elements are path markers, and there is no isolation in the backend data storage.
Tag naming
Please do not use latest to update the image tag in a production environment, which may affect service updates and rollbacks.
We recommend that you use the CI tool for the automatic naming of images to facilitate subsequent tag management and image synchronization.
Please note: When deleting a specified image version, images with the same digest will be deleted simultaneously.
CI/CD
The CI/CD service comes with the Enterprise Edition.
The Enterprise Edition CI/CD capabilities are entirely based on Tencent Cloud CODING DevOps product. You need to activate this product and complete the basic configuration. For more information, see CODING DevOps.
Image building is supported. The optional code sources include GitHub, GitLab, TGit, Gitee, and CODING.
Delivery pipeline is supported, which enables you to automatically deploy images in clusters, elastic clusters, and edge clusters.
External services can be connected.
You can use the trigger (webhook) feature to integrate with existing CI/CD systems. Pushing an image will automatically trigger a webhook notification, with the message body containing the image's basic information. For more details, see Managing Triggers.
You can directly use the complete service of CODING DevOps, which has built-in TCR templates.