Transition to repositories with gcr.io domain support

Stay organized with collections Save and categorize content based on your preferences.

If you currently use Container Registry to manage your container images, this page explains how to set up Artifact Registry repositories with gcr.io domain support. A gcr.io repository in Artifact Registry has some features that are backwards-compatible with Container Registry.

These instructions are primarily for repository administrators. To learn about how building, pushing, pulling, and deploying images has changed, see the following information:

Before you begin

Learn about pricing for Artifact Registry before you begin the transition.

Overview

Artifact Registry repositories with gcr.io domain support provide several backwards-compatible features:

  • Automatically redirect requests for Container Registry hostnames to Artifact Registry gcr.io repositories.
  • Use either gcloud container images or the equivalent gcloud artifacts commands.

If you have a lot of existing automation to transition, these features can help you transition to Artifact Registry more quickly. However, to provide backwards compatibility, gcr.io repositories in Artifact Registry have some feature limitations and might not support new Artifact Registry features.

Standard repositories and repositories with gcr.io domain support can co-exist so that you can gradually transition. For example:

  • You can create gcr.io repositories in Artifact Registry to transition your existing Container Registry setup and create standard repositories for new work.
  • You can take a multi-staged approach to your transition. Transition to gcr.io repositories in Artifact Registry, then gradually shift to using to standard repositories as you update your automation to fully support Artifact Registry repository and image paths.

Otherwise, if you need full Artifact Registry feature support or want to ensure new features are available for your repositories, transition directly to standard repositories.

Limitations

The following limitations apply to repositories with gcr.io domain support:

  • You cannot map a Container Registry host to an Artifact Registry repository in a different project.
  • Each Container Registry hostname maps to only one corresponding Artifact Registry gcr.io repository in the same multi-region.
  • Names for gcr.io repositories are predefined and you can't modify them.
  • gcloud artifacts docker commands don't support shortened digests. If you specify an image with a digest, you must specify the full digest string.

Mapping Container Registry hosts to Artifact Registry repositories

The following example shows how a Container Registry image path and the corresponding image path in a gcr.io repository when redirection is enabled. Although users of your repositories won't need to use Artifact Registry repository and image paths, understanding the mapping for redirection is useful as you set up and test your gcr.io repositories.

Container Registry. Artifact Registry.
Project: my-project Project: my-project
Registry hostname: gcr.io Repository name: gcr.io
Image path: gcr.io/my-project/my-image Image path: us-docker.pkg.dev/my-project/gcr.io/my-image

Transition steps

This guide shows you how to complete the following steps:

  1. Enable required APIs.
  2. Update Google Cloud CLI and learn about the new gcloud commands.
  3. Create Docker repositories for Container Registry hosts in the project.
  4. Grant permissions to the repository.
  5. Configure authentication so that you can connect with your new repository.
  6. If needed, copy images from Container Registry that you want to use in your new repository.
  7. Enable redirection so that you can verify that existing push and pull requests to gcr.io in your automation use your new Docker repositories.
  8. Configure additional features.
  9. Verify that your existing automation can push and pull images. You can reroute traffic back to Container Registry if you need to address issues that occur when redirection is enabled.
  10. When you are confident that your repositories are working as expected, Clean up images in Container Registry.

Enable required APIs

Enable the Artifact Registry and Resource Manager APIs. Artifact Registry uses the Resource Manager API to check for one of the required permissions.

Run the following command:

gcloud services enable \
    cloudresourcemanager.googleapis.com \
    artifactregistry.googleapis.com

Update and configure Google Cloud CLI

Container Registry uses gcloud container images commands.

Artifact Registry uses gcloud artifacts commands for images.

  1. Install gcloud CLI if it is not already installed.

  2. Update the gcloud components.

    gcloud components update
    

gcloud command comparison

The following table summarizes Container Registry commands and the equivalent Artifact Registry commands in the gcloud CLI. Click a link in the table to view reference page for the command.

The table does not include all available Artifact Registry commands that have no equivalent in Container Registry. See the gcloud artifacts documentation for the full Artifact Registry command reference.

Operation Container Registry Artifact Registry
Create a repository Not applicable. gcloud artifacts repositories create
Delete a repository Not applicable. gcloud artifacts repositories delete
List images gcloud container images list gcloud artifacts docker images list
List tags gcloud container images list-tags gcloud artifacts docker tags list
Add a tag gcloud container images add-tag gcloud artifacts docker tags add
Delete a tag gcloud container images untag gcloud artifacts docker tags delete
Describe images gcloud container images describe gcloud artifacts docker image list --include-tags

Create repositories

Container Registry automatically creates a storage bucket in a multi-region if you have not pushed an image there before. In Artifact Registry, you must create a repository before you can upload images.

You can use a special panel in Google Cloud console to create gcr.io repositories quickly, or you can create gcr.io repositories manually.

Quick repository creation

These steps create gcr.io repositories in Artifact Registry for existing Container Registry hosts in your project. The repositories are encrypted with Google-managed encryption keys. If you want to use customer-managed encryption keys (CMEK), you must create repositories manually.

To create gcr.io repositories for your Container Registry hosts:

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

    On the page, a banner displays the message You have gcr.io repositories in Container Registry. If you dismissed the banner or if the banner does not appear, open the Settings page instead.

    Open the Settings page

  2. In the banner, click Create gcr.io repositories.

    The Create gcr.io repositories panel displays a list Container Registry hostnames in your project.

  3. Select hostnames that you want to transition to Artifact Registry. Artifact Registry displays the full path for the corresponding gcr.io repository below the hostname list.

  4. Click Create.

Artifact Registry creates repositories for each hostname you selected and adds them to the repository list. To quickly see the Artifact Registry URL for the repository, hover over the warning icon ( ) next to the repository name.

Before you redirect traffic to your new repositories, you need to make sure that your existing automation can access the repository. The next step is configuring permissions to grant access to repositories.

Manual repository creation

Manually create gcr.io repositories if you dismissed the banner with the quick option for repository creation, or if you want to use customer-managed encryption keys (CMEK) to encrypt repository content.

To manually create a gcr.io repository:

  1. If you are using CMEK, create the key you will use with this repository and grant permissions to use the key. See Enabling customer-managed encryption keys.

  2. Add the repository.

    Console

    1. Open the Repositories page in the Google Cloud console.

      Open the Repositories page

    2. Click Create Repository.

    3. Specify the repository name.

      Container Registry hostname Artifact Registry repository name
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io
    4. Specify Docker as the repository format.

    5. Under Location Type, specify the multi-region for the repository:

      Container Registry hostname Artifact Registry repository location
      gcr.io us
      asia.gcr.io asia
      eu.gcr.io europe
      us.gcr.io us
    6. Add a description for the repository. Do not include sensitive data, since repository descriptions are not encrypted.

    7. In the Encryption section, choose the encryption mechanism for the repository.

      • Google-managed key - Encrypt repository content with a Google-managed encryption key.
      • Customer-managed key - Encrypt repository content with a key that you control through Cloud Key Management Service. For key setup instructions, see Setting up CMEK for repositories.
    8. Click Create.

    gcloud

    Run the following command to create a new repository.

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker [--location=LOCATION] \
    [--description=DESCRIPTION] [--kms-key=KMS-KEY] [--async]
    

    Replace the following values:

    • REPOSITORY is the name of the repository. For each repository location in a project, repository names must be unique.

      Container Registry hostname Artifact Registry repository name
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io
    • LOCATION is the multi-region for the repository:

      Container Registry hostname Artifact Registry repository location
      gcr.io us
      asia.gcr.io asia
      eu.gcr.io europe
      us.gcr.io us
    • DESCRIPTION is a description of the repository. Do not include sensitive data, since repository descriptions are not encrypted.

    • KMS-KEY is the full path to the Cloud KMS encryption key, if you are using a customer-managed encryption key to encrypt repository contents. The path is in the format:

      projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY
      

      Where

      • KMS-PROJECT is the project where your key is stored.
      • KMS-LOCATION is the location of the key.
      • KEY-RING is the name of the key ring.
      • KEY is the name of the key.
    • --async returns immediately, without waiting for the operation in progress to complete.

    You can confirm that the repository is created by listing your repositories with the command:

    gcloud artifacts repositories list
    

Before you redirect traffic to your new repositories, you need to make sure that your existing automation can access the repository. The next step is configuring permissions to grant access to repositories.

Grant permissions to repositories

Container Registry uses Cloud Storage roles to control access. Artifact Registry has its own IAM roles and these roles separate read, write, and repository administration roles more clearly than Container Registry.

To find out which users and service accounts have access to Container Registry, and better understand which ones require access to Artifact Registry, view the list of principals that have access to the Cloud Storage bucket for each of your Container Registry hosts.

  1. In the Google Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. Click the storage bucket for the registry host you want to view. In the bucket names, PROJECT-ID is your Google Cloud project ID.

    • gcr.io: artifacts.PROJECT-ID.appspot.com
    • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
    • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
    • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com
  3. Click the Permissions tab.

  4. On the Permissions tab, click the View by role subtab.

  5. Expand a role to view the principals who have that role.

The list includes IAM roles granted directly on the bucket and roles inherited from the parent project. Based on the role, you can choose the most appropriate Artifact Registry role to to grant.

Cloud Storage or basic roles

Grant principals with these roles with access to Artifact Registry repositories. For roles inherited from the parent project, you should verify that the principal currently uses Container Registry. Some principals might only access other Cloud Storage buckets or other resources in the project.

Current role Artifact Registry role
Viewer or Storage Object Viewer Artifact Registry Reader

Read only

Editor or Storage Legacy Bucket Writer Artifact Registry Writer

Read and write artifacts

Owner or Storage Admin (administrator) One of the following roles, based on the permission requirements of the administrator:
  • Artifact Registry Repository Administrator: Read, write, and delete artifacts
  • Artifact Registry Administrator: Read, write, and delete artifacts. Create and delete repositories. Set permissions on repositories
Service agent roles inherited from the project

Default service accounts for Google Cloud services have their own roles granted at the project level. For example the service agent for Cloud Run has the Cloud Run Service Agent role.

In most cases, these service agent roles contain equivalent default permissions for Container Registry and Artifact Registry and you do not need to make any additional changes if you are running Artifact Registry in the same project as your existing Container Registry service.

Cloud Build has permissions to create Cloud Storage buckets for Container Registry hosts that do not exist in the project, but does not have permissions to create Artifact Registry repositories. A user with Artifact Registry Administrator access must create repositories before you can push images to them with Cloud Build.

Refer to the service agent role reference for details on the permissions in service agent roles.

Custom roles

Use the role mappings for Cloud Storage roles to help you decide on the permissions to grant to principals.

For instructions on granting Artifact Registry roles, see Granting permissions.

Configure authentication for Docker

Artifact Registry supports the same authentication methods as Container Registry. You can continue to use your existing Docker clients with Artifact Registry.

If you use the Docker credential helper for authentication, it only supports gcr.io hostnames by default. If you need to connect to pkg.dev hostnames as well as gcr.io hostnames, you can add the required hostnames to the credential helper configuration. For more information, see Setting up authentication for Docker.

Copy containers from Container Registry

If there are containers in Container Registry that you want to continue to use in Artifact Registry, there are several options for copying them. For detailed instructions, see Copying images from Container Registry

When you specify the destination gcr.io repository, use the Artifact Registry path of the repository is in the format:

LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

Where:

  • LOCATION is the multi-region where the repository is located.

    Container Registry hostname Artifact Registry repository location
    gcr.io us
    asia.gcr.io asia
    eu.gcr.io europe
    us.gcr.io us
  • PROJECT is the project ID

  • REPOSITORY is the repository name:

    Container Registry hostname Artifact Registry repository name
    gcr.io gcr.io
    asia.gcr.io asia.gcr.io
    eu.gcr.io eu.gcr.io
    us.gcr.io us.gcr.io

To quickly see the Artifact Registry URL for a gcr.io repository you created in the Google Cloud console, hover over the warning icon ( ) next to the repository name.

Examples

The following example commands use the gcrane tool to copy all images in a Container Registry host to the corresponding Artifact Registry gcr.io repository in the project my-project.

For gcr.io:

gcrane cp -r gcr.io/my-project us-docker.pkg.dev/my-project/gcr.io

For asia.gcr.io:

gcrane cp -r asia.gcr.io/my-project asia-docker.pkg.dev/my-project/asia.gcr.io

For eu.gcr.io:

gcrane cp -r eu.gcr.io/my-project europe-docker.pkg.dev/my-project/eu.gcr.io

For us.gcr.io:

gcrane cp -r us.gcr.io/my-project us-docker.pkg.dev/my-project/us.gcr.io

Set up other features

This section describes configuration for other features that you might have set up in Container Registry.

Container Analysis

Container Analysis supports both Container Registry and Artifact Registry. The Container Analysis documentation includes both products.

  • Both products use the same Container Analysis APIs. When you enable Container Analysis APIs in either Container Registry or Artifact Registry the APIs are turned on for both products.
  • Both products use the same Pub/Sub topics for Container Analysis notifications. After you enable redirection, any existing subscriptions will include notifications for images in gcr.io repositories.
  • You can continue to use gcloud container images commands to list notes and occurrences associated with gcr.io image paths.

Container Analysis supports both Container Registry and Artifact Registry. The Container Analysis documentation includes both products.

Container Registry Artifact Registry
Scans for OS and language package vulnerabiities with on-demand scanning in images with a supported OS. Automatic scanning only returns OS vulnerability information. Learn more about types of scanning.
On-demand scanning
Automatic scanning
Scans for OS and lanaguage package vulnerabiities with both on-demand and automatic scanning. Learn more about types of scanning.
On-demand scanning
Automatic scanning
  • The Google Cloud CLI command gcloud artifacts docker images includes flags for viewing scan results, including vulnerabilities and other metadata.
  • Scans return OS vulnerability information for images in Artifact Registry with supported operating systems and language package vulnerability information for both supported and unsupported operating systems.

Pub/Sub notifications

Artifact Registry publishes changes to the same gcr topic as Container Registry. No additional configuration is required if you already use Pub/Sub with Container Registry in the same project as Artifact Registry. However, Artifact Registry does not publish messages for gcr.io repositories until you enable redirection. After you enable redirection, the gcr topic will include notifications for both Artifact Registry and Container Registry.

If you set up Artifact Registry in a separate project, the gcr topic might not exist. For setup instructions, see Configuring Pub/Sub notifications.

Enable redirection of gcr.io traffic

After you have created your gcr.io repositories and configured permissions and authentication for your third-party clients, you can enable redirection of gcr.io traffic.

If you encounter an issue after enabling redirection, you can route traffic back to Container Registry and then turn on redirection again when you have addressed the issue.

Verify permissions to enable redirection

To enable redirection, you must have these permissions at the project level:

  • artifactregistry.projectsettings.update: Permissions to update Artifact Registry project settings. This permission is in the Artifact Registry Repository Administrator role (roles/artifactregistry.repoAdmin).
  • storage.buckets.update - Permissions to update storage buckets across the entire project. This permission is in the Storage Admin role (roles/storage.admin).

If you don't have these permissions, ask an administrator to grant them at the project level.

The following commands grant the Artifact Registry Repository Administrator and Storage Admin roles on a project.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL \
    --role=roles/artifactregistry.repoAdmin

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=PRINCIPAL \
    --role=roles/storage.admin

Replace the following values:

  • PROJECT_ID is Google Cloud project ID.
  • PRINCIPAL is the email address for the account that you are updating. For example user:my-user@example.com

Validate project setup

To validate your project setup, run the following command:

gcloud beta artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Replace PROJECT_ID with your Google Cloud project ID.

Artifact Registry checks for repositories that map to Container Registry hostnames.

If all your Container Registry hosts have a corresponding Artifact Registry Docker repository, the output looks like the following example:

Redirection enablement report:

Container Registry Host  Location  Artifact Registry Repository
gcr.io                   us        projects/my-project/locations/us/repositories/gcr.io
eu.gcr.io                eu        projects/my-project/locations/us/repositories/eu.gcr.io

PASS: Redirection enablement checks passed.

Dry run enabled, no changes made.

If a hostname in your project does not have a corresponding gcr.io repository, Artifact Registry displays a warning. For example, if the gcr.io hostname does not have a corresponding Artifact Registry Docker repository named gcr.io, the output includes a warning similar to this one:

WARNING: Not all Container Registry repositories have Artifact Registry
repositories created to handle redirected requests.

Container Registry repository 'gcr.io' should redirect to an Artifact Registry
Docker repository in location 'us' named 'gcr.io'. This repository can be
created with:

gcloud artifacts repositories create gcr.io --location=us --project=my-project
--repository-format=DOCKER

If Artifact Registry repositories are not created, the following Container
Registry repositories will no longer serve requests:
gcr.io

Turn on redirection

To turn on redirection for gcr.io traffic:

Console

  1. Open the Settings page in the Google Cloud console.

    Open the Settings page

  2. Click Route to Artifact Registry.

gcloud

To enable redirection, run the command:

gcloud beta artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Replace PROJECT_ID with your Google Cloud project ID.

The command returns a list of redirected Container Registry hosts. For example:

Container Registry Host  Location  Artifact Registry Repository
gcr.io                   us        projects/my-project/locations/us/repositories/gcr.io

To check the current status of redirection, run the following command:

gcloud beta artifacts settings describe

When redirection is enabled, the result is:

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

All traffic to gcr.io, asia.gcr.io, eu.gcr.io, and us.gcr.io is redirected, even if you did not create gcr.io repositories for all Container Registry hostnames. For example, if the project my-project has gcr.io repositories for all Container Registry hostnames except eu.gcr.io, requests to push to or pull from eu.gcr.io/my-project will return a 404 Not Found error.

With redirection enabled, you can test your automation and verify that you can push and pull images using your new gcr.io repositories. If needed, you can reroute traffic back to Container Registry and then re-enable redirection when you are ready to continue testing.

Routing traffic back to Container Registry

If needed, you can route gcr.io traffic back to Container Registry. You can enable redirection again when you're ready.

Console

  1. Open the Settings page in the Google Cloud console.

    Open the Settings page

  2. Click Route back to Container Registry.

gcloud

  1. Run the following command:

    gcloud beta artifacts settings disable-upgrade-redirection \
        --project=PROJECT_ID
    

    Replace PROJECT_ID with your Google Cloud project ID.

    Artifact Registry prompts you to confirm.

  2. To confirm the rerouting back to Container Registry, enter y.

Verify redirection

Verify that pull and push requests to gcr.io hostnames are working.

  1. Push a test image to one of your gcr.io repositories using its gcr.io path.

    1. Tag the image using the gcr.io path. For example, this command tags the image local-image as us.gcr.io/my-project/test-image:

      docker tag local-image us.gcr.io/my-project/test-image
      
    2. Push the image you tagged. For example, this command pushes the image us.gcr.io/my-project/test-image:

      docker push us.gcr.io/my-project/test-image
      
  2. List images in the repository to verify that the image was uploaded successfully. For example, to list images in us.gcr.io/my-project, run the command:

    gcloud container images list --repository=us.gcr.io/my-project
    
  3. Pull the image from the repository using its Container Registry path. For example, this command pulls the image us.gcr.io/my-project/test-image.

    docker pull us.gcr.io/my-project/test-image
    

After this initial test, verify that your existing automation to build and deploy images works as expected, including:

  • Users and service accounts that use Container Registry can still push, pull, and deploy images when redirection is enabled.
  • Your automation only pushes images to existing repositories.
  • If Container Analysis vulnerability scanning is enabled, scanning identifies images with vulnerabilities in gcr.io repositories.
  • If you use Binary Authorization, your existing policies work correctly for images deployed from gcr.io repositories.
  • Configured Pub/Sub subscriptions include notifications for changes in your gcr.io repositories.

Clean up Container Registry images

When redirection is enabled, commands to delete images in gcr.io paths delete images in the corresponding Artifact Registry gcr.io repository. They do not delete images stored on Container Registry hosts. To safely remove all Container Registry images, delete the Cloud Storage buckets for each Container Registry hostname.

To clean up, delete each Container Registry storage bucket:

Console

  1. Go to the Cloud Storage page in the Google Cloud console.
  2. Select storage bucket to delete. In the bucket names, PROJECT-ID is your Google Cloud project ID.

    • gcr.io: artifacts.PROJECT-ID.appspot.com
    • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
    • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
    • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com
  3. Click Delete. A confirmation dialog box appears.

  4. To confirm deletion, enter the bucket name and then click Delete.

gsutil

If you want to bulk delete a hundred thousand or more images in a bucket, avoid using gsutil since the deletion process takes a long time to complete. Use Google Cloud console to perform the operation instead.

To delete a bucket, use the [gsutil rm][/storage/docs/gsutil/commands/rm] command with the -r flag.

gsutil rm -r gs://BUCKET-NAME

Replace BUCKET-NAME with the Container Registry storage bucket name. In the bucket names, PROJECT-ID is your Google Cloud project ID.

  • gcr.io: artifacts.PROJECT-ID.appspot.com
  • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
  • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
  • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

The response looks like the following example:

Removing gs://artifacts.my-project.appspot.com/...

If other Google Cloud services are running in the same Google Cloud project, leave the Container Registry API enabled. If you try to disable the Container Registry API. Container Registry displays a warning if other services with a configured dependency are enabled in the project. Disabling the Container Registry API automatically disables any services in the same project with a configured dependency, even if you are not currently using Container Registry with those services.

What's next