Set up repositories with gcr.io domain support

Artifact Registry can host your existing Container Registry images and automatically redirect requests for gcr.io hosts to corresponding Artifact Registry repositories. Redirection lets you continue to use image paths with the gcr.io domain in your existing automation and workflows.

Before you begin

  1. Install the Google Cloud CLI if it is not already installed. For an existing installation, run the following command to update components to the latest versions:

    gcloud components update

  2. Enable the Artifact Registry and Resource Manager APIs. gcloud CLI 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

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

Required roles

To get the permissions that you need to set up gcr.io repositories, ask your administrator to grant you the following IAM roles on the Google Cloud project:

  • To create Artifact Registry repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin)
  • To view and manage existing Container Registry configuration applied to Cloud Storage storage buckets: Storage Admin (roles/storage.admin)
  • To create a gcr.io repository the first time you push an image to a gcr.io hostname: Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter)
  • To grant repository access at the project level: Project IAM Admin (roles/resourcemanager.projectIamAdmin) or a role that includes equivalent permissions such as Folder Admin (roles/resourcemanager.folderAdmin), or Organization Admin (roles/resourcemanager.organizationAdmin)

For more information about granting roles, see Manage access.

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

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.

If you need more control over the location of your repositories, you can transition to standard repositories on the Artifact Registry pkg.dev domain. Since standard repositories do not have any support for the gcr.io domain, this transition approach requires more changes to your existing automation and workflows. See Choose a transition option to learn about feature differences.

Create repositories

Create gcr.io repositories so that you can configure access for your users and copy existing Container Registry images to Artifact Registry before you enable redirection.

Quick repository creation

These steps create gcr.io repositories that 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:

  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.

    Open the Settings page

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

    The Create gcr.io repositories panel opens. The Copying images section lists the fully-qualified names of each repository that will be created. You will need these repository names if you want to copy images from Container Registry before you turn on redirection.

  3. Click Create.

Artifact Registry creates gcr.io repositories for all Container Registry hostnames:

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 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 want to use customer-managed encryption keys (CMEK) to encrypt repository content or if there is a location constraint in your Google Cloud organization that blocks creation of new resources in specific locations.

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

    Replace the following values:

    • REPOSITORY is the name of the repository.

      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

      Replace the following values:

      • 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.

    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 quickly map existing permissions granted on storage buckets to suggested Artifact Registry roles, use the role mapping tool.

Alternatively, you can view a list of principals with access to storage buckets using Google Cloud console.

  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 and basic roles

Grant users and service accounts that currently access Container Registry with access to Artifact Registry repositories. For Cloud Storage 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 that are unrelated to Container Registry.

The basic roles Owner, Editor, and Viewer that existed prior to IAM have limited access to storage buckets. They do not intrinsically give all of the access to Cloud Storage resources that their names imply and provide additional permissions for other Google Cloud services. Verify which users and service accounts require access to Artifact Registry and use the role mapping table to help you grant the right roles if Artifact Registry access is appropriate.

The following table maps Artifact Registry roles based on the permissions granted by predefined Cloud Storage roles for Container Registry access.

Required access Current role Artifact Registry role Where to grant role
Pull images only (read only) Storage Object Viewer
(roles/storage.objectViewer)		 Artifact Registry Reader
(roles/artifactregistry.reader) 		Artifact Registry repository or Google Cloud project
  • Push and pull images (read and write)
  • Delete images
 Storage Legacy Bucket Writer
(roles/storage.legacyBucketWriter)		 Artifact Registry Repository Administrator
(roles/artifactregistry.repoAdmin)		 Artifact Registry repository or Google Cloud project
Create a gcr.io repository in Artifact Registry the first time an image is pushed to a gcr.io hostname in a project. Storage Admin
(roles/storage.admin)		 Artifact Registry Create-on-push Repository Administrator
(roles/artifactregistry.createOnPushRepoAdmin)		 Google Cloud project
Create, manage, and delete repositories Storage Admin
(roles/storage.admin)		 Artifact Registry Administrator
(roles/artifactregistry.Admin)		 Google Cloud project
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.

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

Custom roles

Use the role mapping table to help you decide on the role to grant to users or service accounts based on the level of access they require.

For instructions on granting Artifact Registry roles, see Configure roles and permissions.

Copy containers from Container Registry

Copy existing images from Container Registry to Artifact Registry. The fastest and most inexpensive method is copying images with gcrane.

To copy images:

  1. Download gcrane and extract the tool from the archive file. Version 0.10.0 or higher is required. To check the version of an existing gcrane installation, run the command:

    gcrane version

  2. Grant the Artifact Registry Google-managed service account the Storage Object Viewer role (roles/storage.objectViewer) so it can read the storage buckets with our Container Registry images. You can remove this role when you no longer need to copy images from Container Registry.

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com' \
    --role='roles/storage.objectViewer'

    Replace PROJECT_ID with the project ID and PROJECT_NUMBER with the project number for the Google Cloud project where Container Registry and Artifact Registry are running.

  3. Run the commands to copy images:

    For gcr.io:

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

    For asia.gcr.io:

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

    For eu.gcr.io:

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

    For us.gcr.io:

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

When you are finished copying images to Artifact Registry, you can remove the Storage Object Viewer role from the Artifact Registry service account with the command:

gcloud projects remove-iam-policy-binding PROJECT_ID \
    --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com' \
    --role='roles/storage.objectViewer'

Set up other features

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

Artifact Analysis

Artifact Analysis supports both Container Registry and Artifact Registry. Both products use the same Artifact Analysis APIs for image metadata and vulnerability scanning, and the same Pub/Sub topics for Artifact Analysis notifications.

However, the following actions only occur when redirection is enabled:

  • Automatic scanning of gcr.io repositories in Artifact Registry.
  • Including gcr.io repository activity in Pub/Sub notifications.

You can continue to use gcloud container images commands to list notes and occurrences associated with gcr.io image paths.

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.

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 Administrator role (roles/artifactregistry.admin).
  • 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 Administrator and Storage Admin roles on a project.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user: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 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.

Although Artifact Registry can create the missing gcr.io repositories for you when you enable redirection, we recommend creating them first so that you can perform these actions before turning on redirection:

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 artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Replace PROJECT_ID with your Google Cloud project ID.

Artifact Registry starts turning on redirection.

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

gcloud 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. If you push an image to a hostname that doesn't have a corresponding Artifact Registry repository, Artifact Registry creates the repository if you have a role with the artifactregistry.repositories.createOnPush permission. The predefined roles Create-on-push Writer (artifactregistry.createOnPushWriter) and Create-on-push Repository Administrator (artifactregistry.createOnPushRepoAdmin) have this permission.

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 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 Artifact 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 delete each Container Registry storage bucket:

Console

  1. Go to the Cloud Storage page in the Google Cloud console.

  2. Select the 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 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