This document guides you through the differences between Container Registry and Artifact Registry for authenticating, pushing, and pulling container images with Docker.
In this guide, comparisons focus on standard Artifact Registry repositories, regular Artifact Registry repositories that are independent of Container Registry and support all Artifact Registry features.
If your administrator set up
repositories with gcr.io domain support, requests
gcr.io hostnames are automatically redirected to a corresponding
Artifact Registry repository. To use a gcr.io repository hosted on
Artifact Registry, you must have an appropriate
Artifact Registry role or a role with
To learn about the differences between Container Registry and Artifact Registry when building with Cloud Build and deploying to Cloud Run or Google Kubernetes Engine, see Changes for Cloud Build, Cloud Run, and GKE.
Use this information to help you adapt existing commands, configuration, or documentation focused on Container Registry with Docker.
Before you begin
This document assumes that you have:
At a high level, the workflow for using Docker with Container Registry or Artifact Registry is the same.
|Container Registry||Artifact Registry|
However, a shortcut for Container Registry is combining the administrator and user roles into a single workflow. This shortcut is common in:
- Quickstarts and tutorials where you are testing in an environment where you have broad permissions.
- Workflows that use Cloud Build, since the Cloud Build service account has permissions to add a registry host in the same Google Cloud project.
The shortcut workflow looks like this:
- Enable the Container Registry API.
- Grant permissions to the account that will access Container Registry.
Authenticate to the registry. The simplest authentication option is using the Docker credential helper in Google Cloud CLI. This is a one-time configuration step.
gcloud auth configure-docker
Build and tag the image. For example, this command builds and tags the image
docker build -t gcr.io/my-project/my-image:tag1
Push the image to the registry. For example:
docker push gcr.io/my-project/my-image:tag1
gcr.ioregistry host does not exist in the project, Container Registry adds the host before uploading the image.
Pull the image from the registry or deploy it to a Google Cloud runtime. For example:
docker pull gcr.io/my-project/my-image:tag1
This workflow relies on the following shortcuts:
- The account that pushes images has the Storage Admin role or a role with the same permissions such as Owner. The broad permissions of this role allow read and write access for all storage buckets in a project, including buckets that are not used by Container Registry.
- When you enable some Google Cloud APIs, the Container Registry API is enabled automatically. This means users of these services have implicit access to Container Registry in the same project. For example, users who can run builds in Cloud Build can push images to registries and add registry hosts by default.
In Artifact Registry, there is a clear separation of administrator and repository user roles that changes the steps in the build and deploy workflow. To adapt the Container Registry workflow for Artifact Registry, make the following changes. Each step links to additional information about modifying the workflow.
New: Enable the Artifact Registry API.
You must enable the Artifact Registry API. Cloud Build and runtime environments such as Cloud Run and GKE do not automatically enable the API for you.
New: Create the target Docker repository if it doesn't already exist. You must create a repository before you can push any images to it. Pushing an image can't trigger creation of a repository and the Cloud Build service account does not have permissions to create repositories.
Grant permissions to the account that will interact with Artifact Registry.
Changed: Authenticate to the repository. If you use the credential helper in gcloud CLI, you must specify the hosts that you want to add to your Docker client configuration. For example, this command adds the host
gcloud auth configure-docker us-central1-docker.pkg.dev
Changed: Build and tag the image.
The following example command is the same as the Container Registry example, but uses an Artifact Registry repository path for the image.
docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Changed: Push the image to the repository using the Artifact Registry path. For example:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Changed: Pull the image from the repository using the Artifact Registry path. For example:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
Enabling the API
- You must enable the Artifact Registry API in addition to the API for other Google Cloud services such as Cloud Build, Cloud Run, and GKE.
The following comparison describes enabling the API for each service:
You must enable the Container Registry API before using Docker or other third-party clients with Container Registry.
When you enable the following Google Cloud APIs, the Container Registry API is also automatically enabled:
- App Engine flexible environment
- Cloud Build
- Cloud Functions
- Cloud Run
- Container Scanning or On-Demand Scanning in Artifact Analysis
- Google Kubernetes Engine
With the default permissions, users who can run builds in Cloud Build, scan containers with Artifact Analysis, or deploy containers to Google Cloud runtimes implicitly have access to images in Container Registry when the registry is in the same project.
You must enable the Artifact Registry API before using Docker clients or other Google Cloud services with Artifact Registry.
Services such as Cloud Build, Cloud Run, and GKE do not automatically enable the Artifact Registry API.
You can enable multiple APIs in the same project using gcloud. For example, to enable the Cloud Build API and the Artifact Registry API, run the command:
gcloud services enable artifactregistry.googleapis.com \ cloudbuild.googleapis.com
Adding registries and repositories
You must create an Artifact Registry Docker repository before you push an image to it.
A registry creation step is often excluded in documentation that describes pushing images to Container Registry because an account with Storage Admin permissions can add a registry to a project with the initial push to the registry host.
Container Registry stores all images in a single multi-region in the same storage bucket. In Artifact Registry, you can create multiple repositories in the same region or multi-region with separate access policies.
The following comparison describes repository setup in each service:
In Container Registry you can add up to four registry hosts to your project. You add a registry host by pushing the first image.
To add a registry such as
gcr.ioto your project, an account with the Storage Admin role at the project level pushes an initial image.
For example, if the
gcr.iohost does not exist in the project
my-project, pushing the image
gcr.io/my-project/my-image:1.0triggers the following steps:
- Add the
gcr.iohost to the project
- Create a storage bucket for
gcr.ioin the project.
- Store the image as
- Add the
After this initial push, you can then grant permissions to the storage bucket for other users.
Within a project, a registry host stores all images in the same storage
bucket. In the following example, the project
my-project has two images called
web-app in the registry
gcr.io. One is directly under the project ID
my-project. The other image is in the repository
In Artifact Registry each repository is a separate resource. Therefore, all image paths must include a repository.
Valid image paths:
Invalid image path (does not include a repository) :
The following examples show situations where pushing an image to a missing repository fails.
- Pushing an image to
us-central1-docker.pkg.dev/my-project/team1does not exist.
- Pushing an image to
us-central1-docker.pkg.dev/my-project/team2does not exist.
- Grant the appropriate Artifact Registry role to the account that you are using with Artifact Registry.
- Google Cloud services have equivalent read or write access to both Container Registry and Artifact Registry. However, the default Cloud Build service account can't create repositories.
- Container Registry supports access control at the storage bucket level. Artifact Registry supports access control at the repository level.
The following comparison describes permissions setup in each service:
Container Registry uses the Cloud Storage roles to control access.
- Storage Object Viewer at the storage bucket level
- Pull (read) images from existing registry hosts in the project.
- Storage Legacy Bucket Writer at the storage bucket level
- Push (write) and pull (read) images for existing registry hosts in the project.
- Storage Admin at the project level
- Add a registry host to a project by pushing an initial image to the host.
After the initial image push to a registry, you grant Cloud Storage roles to other accounts that require access to the storage bucket. Note that any account with all permissions in the Storage Admin role can read, write, and delete storage buckets and storage objects across the entire project.
Permissions on a storage bucket apply to all repositories in the registry.
For example, any user with Storage Object Viewer permissions on the
gcr.io/my-project can read images in all these repositories:
gcr.io/my-project/team1 gcr.io/my-project/team2 gcr.io/my-project/test gcr.io/my-project/production
Artifact Registry has its own roles to control access. These roles provide clear separation between administrator and repository user roles.
Only accounts that manage repositories should have the Artifact Registry Repository Administrator or Artifact Registry Administrator role.
- Artifact Registry Reader
- List artifacts and repositories. Download artifacts.
- Artifact Registry Writer
- List artifacts and repositories. Download artifacts, upload new artifact versions, and add or update tags.
- Artifact Registry Repository Administrator
- Artifact Registry Writer permissions and permissions to delete artifacts and tags.
- Artifact Registry Administrator
- Artifact Registry Repository Administrator permissions and permissions to create, update, delete, and grant permissions to repositories.
You can apply these permissions at the repository level. For example:
- Grant access to Team 1 for
- Grant access to Team 2 for
For details about granting Artifact Registry permissions, see the access control documentation.
Authenticating to the registry
- Artifact Registry supports the same authentication methods as Container Registry.
- For the Docker credential helper, you must specify hosts to add to the Docker client configuration.
- For authentication using
docker login, use the Artifact Registry host instead of a Container Registry host.
Using the credential helper
gcloud auth configure-docker and the standalone credential helper
only configures Docker for
*.gcr.io hostnames by default. For Artifact Registry,
you must specify a list of the Artifact Registry hosts you want to add to the Docker client
For example, to set up authentication to Docker repositories in the region
us-central1, run the following command:
gcloud auth configure-docker us-central1-docker.pkg.dev
If you later add repositories in
asia-east1, you must run
the command again to add the corresponding regional hostnames to your
gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev
For details Artifact Registry authentication methods, see Setting up authentication for Docker.
Using password authentication
When you log in to Docker, use the Artifact Registry hostname instead of
*.gcr.io hostname. The following example shows authentication with a
base64-encoded service account key to the host
cat key.json | docker login -u _json_key_base64 --password-stdin \ https://us-central1-docker.pkg.dev
Building and tagging images
Key points: - Artifact Registry uses a different host name for repositories.
When you tag an image, use the Artifact Registry path instead of the Container Registry path. For example:
docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Pushing images to the registry
Key points: - In Artifact Registry, the target repository must exist before you push an image to it. - Artifact Registry uses a different host name for repositories.
When you push an image, use the Artifact Registry path instead of the Container Registry path. For example:
docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
Pulling images from the registry
- The Artifact Registry hostnames are different than Container Registry hostnames.
When you pull an image, use the Artifact Registry path instead of the Container Registry path. For example:
docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0
For examples of deploying images to Google Cloud runtimes such as Cloud Run and GKE, see Deploying images.