Transition to standard repositories

If you use Container Registry to manage your container images, this page explains how to set up a pkg.dev Artifact Registry repository and how using repositories differs from using 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:

• Changes to building and deploying in Google Cloud
• Changes to pushing and pulling with Docker

Before you begin

1. Enable the Artifact Registry API from the Google Cloud console or with the command:

   gcloud services enable artifactregistry.googleapis.com
   

2. Install gcloud 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
   

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 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 to projects, folders, and organizations.

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

Overview

pkg.dev repositories are regular Artifact Registry repositories that support all features.

For simplicity, the instructions on this page assume that both Container Registry and Artifact Registry are in the same Google Cloud project. You can continue to use both services as you transition to Artifact Registry so that you can gradually perform the setup steps and update your automation. If required, you can set up Artifact Registry in a separate project and perform the same overall steps.

Artifact Registry also offers gcr.io repositories. These repositories can redirect gcr.io traffic from your existing registries to corresponding Artifact Registry repositories. They provide some backwards compatibility with Container Registry, but they also have some feature limitations. However, if you have a lot of tool configuration, scripts, or code with gcr.io references, a more tactical approach might be necessary to transition to Artifact Registry. Review the transition documentation for repositories with gcr.io domain support to help you make an appropriate decision.

Transition steps

This guide will shows you how to complete the following steps:

1. Create a Docker repository for your containers. You must create a repository before you can push images to it.
2. Grant permissions to the repository.
3. Configure authentication so that you can connect with your new repository.
4. If needed, copy images from Container Registry that you want to use in your new repository.
5. Try pushing and pulling your containers.
6. Try deploying your images to a runtime environment.
7. Configure additional features.
8. Clean up images in Container Registry when the transition is complete.

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. When you create a repository you must specify:

• The repository format. Artifact Registry stores containers in Docker repositories.

• A regional or multi-regional location for the repository.

  When choosing a location for your Artifact Registry repositories, consider the proximity of the repositories to your other infrastructure and your users. If you intend to copy images from Container Registry to Artifact Registry, differences in location can impact the cost of copying.

• A Cloud Key Management Service key, if you are using customer-managed encryption keys (CMEK) for encryption.

  In Container Registry, you configure the Container Registry storage bucket to use CMEK. In Artifact Registry, you configure repositories to use CMEK when you create them. For more information about using CMEK with Artifact Registry, see Enabling customer-managed encryption keys.

Container Registry hosts containers on the domain gcr.io. Artifact Registry hosts containers on the domain pkg.dev.

For information about creating repositories, including repositories that use CMEK for encryption, see Creating repositories.

Grant permissions

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 the 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. Artifact Registry roles provide some additional separation of permissions that is not available in the predefined Cloud Storage roles.

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)	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Writer (roles/artifactregistry.writer)	Artifact Registry repository or Google Cloud project
Push, pull, and delete images	Storage Legacy Bucket Writer (roles/storage.legacyBucketWriter)	Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)	Artifact Registry repository or 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.

Authenticate to the repository

Artifact Registry supports the same authentication methods as Container Registry.

If you are using the Docker credential helper:

• You must use version 2.0 or later to interact with Artifact Registry repositories. The standalone version is available in GitHub.
• You must configure the credential helper with the Artifact Registry locations that you intend to use. By default the credential helper only configures access to Container Registry hosts.

For details about setting up authentication, 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

Push and pull images

The Docker commands that you use to tag, push, and pull images in Artifact Registry are similar to the ones you use in Container Registry. There are two key differences:

• The hostname for Artifact Registry Docker repositories include a location prefix, followed by -docker.pkg.dev. Examples include australia-southeast1-docker.pkg.dev, europe-north1-docker.pkg.dev, and europe-docker.pkg.dev.
• Since Artifact Registry supports multiple Docker repositories in a single project, you must specify the repository name in commands.

For example, in Container Registry, this command pushes the image my-image to the registry eu.gcr.io in the project my-project.

docker push eu.gcr.io/my-project/my-image

In Artifact Registry, this command pushes the image my-image to the regional repository europe-north1-docker.pkg.dev in repository my-repo and the project my-project.

docker push europe-north1-docker.pkg.dev/my-project/my-repo/my-image

For details about pushing and pulling images in Artifact Registry, see Pushing and pulling images.

Deploy images

Service accounts for common Google Cloud integrations are configured with default permissions for repositories in the same project.

Building images and pushing them to a repository with Cloud Build generally works the same way as it does for Container Registry. The key difference in Artifact Registry is that a target repository must exist before you push images to it, including the first image that you push.

Ensure that you create the repositories that you need before running commands that push images, including the Docker command docker push and the Cloud Build command gcloud builds submit.

Cloud Build builders are still hosted on gcr.io. For more information, see Integrating with Cloud Build.

Other features

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

Artifact Analysis

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

• Both products use the same Artifact Analysis APIs. When you enable Artifact 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 Artifact Analysis notifications.
• You can continue to use gcloud container images commands to list notes and occurrences associated with gcr.io image paths.

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.

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

Service perimeters

With VPC Service Controls, you can configure security perimeters around the resources of your Google-managed services and control the movement of data across the perimeter boundary.

See Securing repositories in a service perimeter for instructions.

Clean up Container Registry images

When you are ready to stop using Container Registry, delete the remaining images by deleting the storage buckets for Container Registry.

To delete each Container Registry storage bucket:

gcloud storage rm gs://BUCKET-NAME --recursive

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

• Try the Docker quickstart.