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.

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:

  • Create gcr.io 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, even if you have already enabled redirection.

Before you begin

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. 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 transitioning to gcr.io repositories in Artifact Registry using the automatic migration tool.

Service account roles:

You can use the gcr.io migration service account with the email address of [email protected] or the Artifact Registry service account to transition to gcr.io repositories in Artifact Registry.

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

Your administrator might also be able to give the service account you are using for the migration the required permissions through custom roles or other predefined roles.

User roles:

To get the permissions that you need to transition to gcr.io repositories hosted on Artifact Registry, 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 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 180 days, you can include the --recent-images=DAYS flag. Replace DAYS with the number of days, between 30 and 180, 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.

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

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 tool skips all migration steps, and copies images in the specified projects from Container Registry to gcr.io repositories hosted on Artifact Registry.

What's next