gcr.io hosted on Artifact Registry by default

Learn how to set up gcr.io repositories in Artifact Registry, and learn about the differences between Artifact Registry and Container Registry permissions and storage bucket configuration.

The manual steps described in this document can be completed using the automatic migration tool. If you want to use the automatic migration tool to transition your projects with active Container Registry usage to Artifact Registry standard repositories or gcr.io repositories, see Automate migration to Artifact Registry.

Container Registry deprecation

Google Cloud projects that have not used Container Registry before May 15, 2024 will only support hosting and managing images in Artifact Registry. This change affects:

Newly created projects.
Existing projects where you have not pushed an image to Container Registry.

Organizations that haven't used Container Registry before January 8, 2024 will have any new gcr.io repositories hosted on Artifact Registry by default.

When you enable the Artifact Registry API in these projects, Artifact Registry will automatically handle creation of gcr.io repositories in Artifact Registry and redirect requests to the gcr.io domain to the appropriate Artifact Registry repository. Unlike existing gcr.io domain support in projects with active Container Registry use, redirection to Artifact Registry will be automatic.

Container Registry will remain available in projects where either of the following actions occurred before May 15, 2024:

You enabled the Container Registry API in the project.
You pushed an image to a registry host in the project.

To prepare for the upcoming change we recommend that you:

Follow the instructions in this document to configure projects where you are not using Container Registry so that they are ready for automatic handling of gcr.io requests when changes take effect.
Test gcr.io domain support to verify that your existing automation will continue to work.

gcr.io repositories hosted on Artifact Registry are created in the same multi-regions that Container Registry supports. If you want to store your images in other regions, you must transition to standard repositories on the pkg.dev domain.

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:

To create Artifact Registry repositories and grant access to individual repositories: Artifact Registry Administrator (roles/artifactregistry.admin) on the project
To view and manage existing Container Registry configuration applied to Cloud Storage storage buckets: Storage Admin (roles/storage.admin) on the project
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) on the project, folder, or organization
To list enabled services in an organization: Cloud Asset Viewer (roles/cloudasset.viewer) on the organization

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.

Before you begin

You can list projects where at least one image is stored in Container Registry. You can then focus on setting up other projects for hosting gcr.io requests in Artifact Registry using the instructions in this document.

Run the following command to find any Container Registry usage in your Google Cloud organization.

  gcloud container images list-gcr-usage \
      --organization=ORGANIZATION

Replace ORGANIZATION with your Google Cloud organization ID.

You can also list Container Registry usage for your project or folder. For more information on finding Container Registry usage, see Check Container Registry usage.

Enable the API

Enable the Artifact Registry API so that requests to the gcr.io domain are automatically handled by Artifact Registry when automatic gcr.io hosting takes effect.

Run the following command:

gcloud services enable \
    artifactregistry.googleapis.com

If you normally place the Container Registry API in a VPC Service Controls service perimeter, make sure you place the Artifact Registry API in the perimeter too. See Securing repositories in a service perimeter for instructions.

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.

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

Go to Buckets
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
Click the Permissions tab.
On the Permissions tab, click the View by role subtab.
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.

Storage bucket configuration

When you create a repository in Artifact Registry, Artifact Registry does not create corresponding Cloud Storage buckets in your project. If you have automation for Container Registry that interacts directly with storage buckets, you must update it to make corresponding changes to the Artifact Registry repository.

For example, if you programmatically grant Cloud Storage permissions on storage buckets for Container Registry, you must update that automation to grant Artifact Registry permissions on the Artifact Registry repositories that host images for the gcr.io domain.

In Artifact Registry, you set the encryption method for stored data on a repository instead of a storage bucket. Automatic gcr.io hosting on Artifact Registry creates gcr.io repositories that are encrypted with Google-managed encryption keys. If you want to use customer-managed encryption keys (CMEK), you must create the gcr.io repositories yourself and specify CMEK as the encryption method when you create them.

To manually create a gcr.io repository:

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.
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 following command:
```
gcloud artifacts repositories list
```

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

Container Registry hostname	Artifact Registry repository location
gcr.io	us
asia.gcr.io	asia
eu.gcr.io	europe
us.gcr.io	us

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

Container Registry hostname	Artifact Registry repository location
gcr.io	us
asia.gcr.io	asia
eu.gcr.io	europe
us.gcr.io	us

What's next

Set up gcr.io domain support in a test project to verify that existing automation and integration with services such as Cloud Build, Google Kubernetes Engine, or Cloud Functions work as expected.