How to Migrate Container Registry Images to Artifact Registry

As Google Cloud transitions from Container Registry to Artifact Registry, it’s crucial to ensure your images are copied over seamlessly. This guide outlines the steps to move your images from Container Registry to Artifact Registry using various tools and methods.

Key Considerations

  • Image Upload Date: The original upload date is preserved only if you use the automatic migration tool. Other methods will set the creation date in Artifact Registry as the date of the copy.
  • Cost Management: Remove old, untagged images and disable automated scanning to reduce costs during the transition.

Overview of Copying Options

  1. Automatic Migration Tool: Recommended for multiple projects and large volumes of images.
  2. gcrane Tool: Suitable for less than 10,000 images and supports batch copying.

Pre-Copying Steps

  1. Remove Untagged Images: Use tools like gcr-cleaner to remove untagged images and save on storage and copying costs.
  2. Disable Automated Scanning: For standard Artifact Registry repositories, disable automated scanning to avoid duplicate costs.

Copying Images with the Automatic Migration Tool

The automatic migration tool simplifies the transition and is ideal for large projects or multiple projects. Follow the detailed instructions in Automatically migrate to Artifact Registry.

Copying Images with gcrane

The gcrane tool is efficient and cost-effective, especially within the same Google Cloud multi-region. Here’s how to set it up and use it:


  • Enabled Artifact Registry in both source and destination projects.
  • Created Docker Repository in Artifact Registry.
  • Necessary Permissions: Ensure you have Storage Object Viewer and Artifact Registry Writer roles.

Setting Up gcrane

  1. Download gcrane:
    sh curl -L -o go-containerregistry.tar.gz tar -zxvf go-containerregistry.tar.gz chmod +x gcrane sudo mv gcrane /usr/local/bin/
  2. Verify Installation:
    sh gcrane --help

Identify Images to Copy

  1. List Existing Images:
    sh gcrane ls
  2. List Tags for an Image:
    sh gcrane ls
  3. List Images Recursively:
    sh gcrane ls -r

Copying Images

  1. Single Image: gcrane cp Example: gcrane cp
  2. Images Under a Path: gcrane cp -r Example: gcrane cp -r
  3. All Images from a Location:
    sh gcrane cp -r
    sh gcrane cp -r

Copying Images with Docker

  1. Pull the Image from Container Registry:
    sh docker pull
  2. Push the Image to Artifact Registry:
    sh docker push

Copying Images with gcloud

  1. Run the gcloud Command:
    sh gcloud container images add-tag GCR-IMAGE AR-IMAGE
    sh gcloud container images add-tag

Environment Options and Costs

  • Compute Engine: Best for large-scale copying. Minimize costs by using VMs in the same region as your registries.
  • Cloud Shell: Ideal for small sets (up to 40GB). Ensure the multi-region matches to avoid extra costs.
  • Local Machine: Use if other options are not available. Follow similar cost-saving practices as for Compute Engine.


By following these steps, you can ensure a smooth and cost-effective transition of your images from Container Registry to Artifact Registry. Choose the method that best suits your project’s needs, and keep an eye on costs by leveraging tools and strategies to manage and optimize your image storage and transfer.