Changes for Docker

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 pkg.dev 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 to 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 equivalent permissions.

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:

1. Enabled Artifact Registry in your project.
2. Installed Docker. Docker is included in Cloud Shell.

Overview

At a high level, the workflow for using Docker with Container Registry or Artifact Registry is the same.

Container Registry	Artifact Registry
Administrator Enable the Container Registry API Add a registry host, such as `gcr.io`, by pushing an initial image to the host. Grant Cloud Storage roles on the storage bucket for the registry host to provide access to images.	Administrator Enable the Artifact Registry API Add a Docker repository. Grant Artifact Registry roles to provide access to images.
Registry users Define the image as a Dockerfile file. Build the image. Authenticate to the registry. Tag and push the image to the registry. Pull the image from the registry or deploy it to a Google Cloud runtime.	Registry users Define the image as a Dockerfile file. Build the image. Authenticate to the registry. Tag and push the image to the registry. Pull the image from the registry or deploy it to a Google Cloud runtime.

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:

1. Enable the Container Registry API.
2. Grant permissions to the account that will access Container Registry.

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

4. Build and tag the image. For example, this command builds and tags the image gcr.io/my-project/my-image:tag1:

   docker build -t gcr.io/my-project/my-image:tag1
   

5. Push the image to the registry. For example:

   docker push gcr.io/my-project/my-image:tag1
   

   If the gcr.io registry host does not exist in the project, Container Registry adds the host before uploading the image.

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

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

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

3. Grant permissions to the account that will interact with Artifact Registry.

4. 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 us-central1-docker.pkg.dev:

   gcloud auth configure-docker us-central1-docker.pkg.dev
   

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

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

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

Key points:

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

Container Registry

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

Artifact Registry

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

Key points:

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

Container Registry

In Container Registry you can add up to four registry hosts to your project. You add a registry host by pushing the first image.

1. To add a registry such as gcr.io to your project, an account with the Storage Admin role at the project level pushes an initial image.

   For example, if the gcr.io host does not exist in the project my-project, pushing the image gcr.io/my-project/my-image:1.0 triggers the following steps:

   1. Add the gcr.io host to the project
   2. Create a storage bucket for gcr.io in the project.
   3. Store the image as gcr.io/my-project/my-image:1.0

2. 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 team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

An account with the Artifact Registry Repository Administrator role must create the repository before you push images to it. You can then grant permissions to the repository for other users.

In Artifact Registry each repository is a separate resource. Therefore, all image paths must include a repository.

Valid image paths:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Invalid image path (does not include a repository) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

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/team1 if us-central1-docker.pkg.dev/my-project/team1 does not exist.
• Pushing an image to us-central1-docker.pkg.dev/my-project/team2 when us-central1-docker.pkg.dev/my-project/team1 exists, but us-central1-docker.pkg.dev/my-project/team2 does not exist.

Granting permissions

Key points:

• 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

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 bucket for 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

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 us-central1-docker.pkg.dev/my-project/team1
• Grant access to Team 2 for us-central1-docker.pkg.dev/my-project/team2.

For details about granting Artifact Registry permissions, see the access control documentation.

Authenticating to the registry

Key points:

• 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

The command 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 configuration.

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 us-east1 and asia-east1, you must run the command again to add the corresponding regional hostnames to your Docker configuration.

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 a *.gcr.io hostname. The following example shows authentication with a base64-encoded service account key to the host us-central1-docker.pkg.dev:

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

Key point:

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