Automatically migrate from Container Registry to Artifact Registry

Use the automatic migration tool to transition from Container Registry to gcr.io repositories hosted on Artifact Registry or to standard Artifact Registry repositories.

Migration to Artifact Registry gcr.io repositories can be performed on Container Registry endpoints receiving traffic without requiring any downtime or service disruption.

The automatic migration tool can perform the following actions depending on the transition path you choose:

Create gcr.io repositories or standard repositories in Artifact Registry for each of your listed gcr.io projects in the corresponding region.
Suggest an IAM policy for each repository and apply the policy or skip application depending on user preference.
Redirect all traffic from gcr.io endpoints to Artifact Registry.
Copy all container images stored in Container Registry to your Artifact Registry gcr.io repositories or standard repositories, even if you have already enabled redirection.

Before you begin

Install the Google Cloud CLI.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
Choose a transition option.

If you are transitioning to gcr.io repositories hosted on Artifact Registry, enable the Artifact Registry API in Container Registry projects you want to migrate. The tool will also prompt you to enable the Artifact Registry API if you skip this step.

Enable the Artifact Registry API.
Enable the API
If you are transitioning to standard Artifact Registry repositories, enable the Artifact Registry API in the project you want to migrate your Container Registry container images to. You can use the same project where Container Registry is enabled, or a different project.

Enable the Artifact Registry API.
Enable the API

Required roles

The following roles are required for all transition options using the automatic migration tool.

Roles required by the Artifact Registry service account:

To ensure that the Artifact Registry service account has the necessary permissions to copy images from Container Registry to Artifact Registry, ask your administrator to grant the Artifact Registry service account the Storage Object Viewer (roles/storage.objectViewer) IAM role on the Container Registry project. For more information about granting roles, see Manage access to projects, folders, and organizations.

Your administrator might also be able to give the Artifact Registry service account the required permissions through custom roles or other predefined roles.

Roles required to generate IAM recommendations:

To get the permissions that you need to analyze an allow policy, ask your administrator to grant you the following IAM roles on the Container Registry project(s) you want to migrate:

Cloud Asset Viewer (roles/cloudasset.viewer)
To analyze policies with custom IAM roles: Role Viewer (roles/iam.roleViewer)
To use the Google Cloud CLI to analyze policies: Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to analyze an allow policy. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to analyze an allow policy:

cloudasset.assets.analyzeIamPolicy
cloudasset.assets.searchAllResources
cloudasset.assets.searchAllIamPolicies
To analyze policies with custom IAM roles: iam.roles.get
To use the Google Cloud CLI to analyze policies: serviceusage.services.use

You might also be able to get these permissions with custom roles or other predefined roles.

The following roles are granted on different resources depending on your transition option.

gcr.io repositories

To get the permissions that you need to transition to gcr.io repositories hosted on Artifact Registry, ask your administrator to grant you the following IAM roles:

Create Artifact Registry repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin) on the Google Cloud project that contains your Container Registry images
View and manage existing Container Registry configuration applied to Cloud Storage storage buckets: Storage Admin (roles/storage.admin) on the Google Cloud project that contains your Container Registry images

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

standard repositories

To get the permissions that you need to transition to standard Artifact Registry repositories, ask your administrator to grant you the following IAM roles:

Create Artifact Registry repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin) on the Google Cloud project where the Artifact Registry API is enabled
View and manage existing Container Registry configuration applied to Cloud Storage storage buckets: Storage Admin (roles/storage.admin) on the Google Cloud project that contains your Container Registry images

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Migrate to gcr.io repositories hosted on Artifact Registry

You can migrate a single Google Cloud project, or multiple Google Cloud projects at the same time using the gcloud artifacts docker upgrade migrate command.

To migrate to gcr.io repositories, run the following command.

gcloud artifacts docker upgrade migrate \
    --projects=PROJECTS

Where PROJECTS is the project ID of a single project you want to migrate to gcr.io repositories hosted on Artifact Registry, or a comma separated list of project IDs that you want to migrate to gcr.io repositories hosted on Artifact Registry.

The migration tool completes the following steps:

Creates gcr.io repositories in Artifact Registry for each of your listed gcr.io projects in the corresponding region.
Suggests an IAM policy for each repository, and applies the policy or skips application depending on user preference.
Redirects all traffic from gcr.io endpoint to Artifact Registry. Artifact Registry temporarily serves missing images by copying them from Container Registry at request time until all container images are copied to Artifact Registry.
Copies all container images stored in your gcr.io buckets to the newly created gcr.io repositories hosted on Artifact Registry.
Disables request-time copying. The gcr.io repository hosted on Artifact Registry no longer depends on Container Registry.

If you only want to copy images pulled from Container Registry in the last 30 to 150 days, you can include the --recent-images=DAYS flag. Replace DAYS with the number of days, between 30 and 150, that the tool should check for pulls within.

If you want to copy a specific number of recently uploaded version of each image, you can include the --last-uploaded-versions=VERSIONS flag. Replace VERSIONS with the number of versions you want to copy for each image. If new images are uploaded during copying, more than the number of versions specified might be copied.

The --recent-images flag and the --last-uploaded-versions flag are mutually exclusive and can't be used together.

If you encounter errors or timeouts, you can safely re-run the command, and completed steps are skipped.

Migrate to standard Artifact Registry repositories

To migrate your gcr.io project to an Artifact Registry repository, run the following command.
```
gcloud artifacts docker upgrade migrate \
    --from-gcr=GCR_HOSTNAME/GCR_PROJECT \
    --to-pkg-dev=AR_PROJECT/AR_REPOSITORY
```
Replace the following:
- GCR_HOSTNAME with the Container Registry hostname. The hostname depends on where your container images are stored:
  - gcr.io hosts the images in the United States.
  - us.gcr.io hosts the images in the United States, in a separate storage bucket from images hosted by gcr.io.
  - eu.gcr.io hosts the images within member states of the European Union.
  - asia.gcr.io hosts the images in Asia.
- GCR_PROJECT with your Container Registry Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
- AR_PROJECT with the Google Cloud project ID where you enabled the Artifact Registry API.
- AR_REPOSITORY with the name for your Artifact Registry repository.

The migration tool completes the following steps:

Creates the Artifact Registry repository if the repository doesn't already exist.
Suggests an IAM policy for the repository, and applies the policy or skips application depending on user preference.
Copies images in the specified Container Registry region and project to your Artifact Registry repository.

If you encounter errors or timeouts, you can safely re-run the command, and completed steps are skipped.

Copy images

The migration tool automatically copies your container images when you run it, but if you want to skip all other steps of the automatic migration, and use the tool to copy images to Artifact Registry you can pass the --copy-only flag.

To copy images from Container Registry to a gcr.io repository hosted on Artifact Registry, run the following command:

gcloud artifacts docker upgrade migrate \
    --projects=PROJECTS \
    --copy-only

The tool skips all migration steps, and copies images in the specified projects from Container Registry to gcr.io repositories hosted on Artifact Registry.

To copy images from Container Registry to a standard Artifact Registry repository, run the following command:

gcloud artifacts docker upgrade migrate \
    --from-gcr=GCR_HOSTNAME/GCR_PROJECT \
    --to-pkg-dev=AR_PROJECT/AR_REPOSITORY \
    --copy-only

Replace the following:

GCR_HOSTNAME with the Container Registry hostname. The hostname depends on where your container images are stored:
- gcr.io hosts the images in the United States.
- us.gcr.io hosts the images in the United States, in a separate storage bucket from images hosted by gcr.io.
- eu.gcr.io hosts the images within member states of the European Union.
- asia.gcr.io hosts the images in Asia.
GCR_PROJECT with your Container Registry Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
AR_PROJECT with the Google Cloud project ID where you enabled the Artifact Registry API.
AR_REPOSITORY with the name for your Artifact Registry repository.

The tool skips all migration steps, and copies images from the specified location and project in Container Registry to your Artifact Registry repository.

You can also use the --copy-only flag to restart copying images if you have an error or timeout during the process.

What's next

Learn about the differences between Container Registry and Artifact Registry for authenticating, pushing, and pulling images with Docker.