Automatically migrate from Container Registry to Artifact Registry

This document describes the steps necessary to transition from Container Registry to pkg.dev Artifact Registry repositories.

Most Container Registry users should transition to gcr.io repositories hosted on Artifact Registry, not pkg.dev repositories, so only follow these instructions if you understand the difference between gcr.io repositories and pkg.dev repositories in Artifact Registry.

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

Create a pkg.dev repository in Artifact Registry for your gcr.io project in the corresponding region.
Suggest an IAM policy for the repository and apply the policy or skip application depending on user preference.
Copy all container images stored in Container Registry to your Artifact Registry pkg.dev repository.

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.
Enable the Artifact Registry API.
Enable the API

The auto-migration tool prompts you to enable the Artifact Registry API if you skip this step.

Required roles

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

Service account roles:

You must grant the following roles to the Artifact Registry service account for each project you want to migrate to Artifact Registry.

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.

User roles:

To get the permissions that you need to transition to pkg.dev Artifact Registry repositories, ask your administrator to grant you the Artifact Registry Container Registry Migration Admin role (roles/artifactregistry.containerRegistryMigrationAdmin) IAM role on the Google Cloud organization or project you want to migrate. 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 `pkg.dev` Artifact Registry repositories

To migrate your gcr.io project to a pkg.dev 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 only want to copy images pulled from Container Registry in the last 30 to 180 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 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 pkg.dev 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.