Overview of Container Registry

Container Registry is a private container image registry that runs on Google Cloud Platform. Container Registry supports Docker Image Manifest V2 and OCI image formats.

Many people use Dockerhub as a central registry for storing public Docker images, but to control access to your images you need to use a private registry such as Container Registry.

You can access Container Registry through secure HTTPS endpoints, which allow you to push, pull, and manage images from any system, VM instance, or your own hardware. Additionally, you can use the Docker credential helper command-line tool to configure Docker to authenticate directly with Container Registry.

Registry name

Registries in Container Registry are named by the host and project ID. To work with images (for example push, pull, delete) identify the image using the following format:





  • [HOSTNAME] is one of four options:

    • gcr.io currently hosts the images in the United States, but the location may change in the future
    • us.gcr.io hosts the image in the United States, in a separate storage bucket from images hosted by gcr.io
    • eu.gcr.io hosts the images in the European Union
    • asia.gcr.io hosts the images in Asia

    When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-regional location. This bucket is the underlying storage for the registry. This location is not your location, but the location where the images is stored. Within a project, all registries with the same hostname share one storage bucket.

  • [PROJECT-ID] is your Google Cloud Platform Console project ID. If your project ID contains a colon (:), see Domain-scoped projects below.

  • [IMAGE] is the image's name. It can be different than the image's local name. In the Google Cloud Platform Console, the project's registries are listed by the image name. Each repository can hold multiple images with the same name. For example, it may hold different versions of an image called "quickstart-image".

  • adding either :[TAG] and @[IMAGE_DIGEST] at the end allows you to distinguish a specific version of the image, but it is also optional. If you don't specify a tag or the digest, Container Registry looks for the image with the default tag latest. See Versions of images within a registry below.

For example, in the quickstart, the registry for the quickstart image is gcr.io/[PROJECT-ID]. To push and pull the image you use the format:


where [PROJECT-ID] is your Google Cloud Platform Console project ID.

Versions of images within a registry

A registry can contain many images, and these images may have different versions. To identify a specific version of the image within a registry, you can specify the image's tag or digest. Tags are unique to one image within a registry. Digests are automatically generated, are unique to a version of an image, and have the form @[IMAGE_DIGEST], where [IMAGE_DIGEST] is the sha256 hash value of the image contents.

For example, in the quickstart, to identify a specific version of the image:

  • add the image's tag:

  • or, add the image's digest:


where [PROJECT-ID] is your Google Cloud Platform Console project ID. If your project ID contains a colon (:), see Domain-scoped projects below.

In the console, on the Images screen, the Tags column lists the image's tags. Click on the version of the image to see metadata, including the Image digest.

See Tagging Images for how to modify tags.

Domain-scoped projects

If your project is scoped to your domain, the project ID includes the name of the domain followed by a colon (:). Because of how Docker treats colons, you must replace the colon character with a forward slash when you specify an image digest in Container Registry. Identify images in these types of projects using the following format:


For example, the project with ID example.com:my-project could have the following image:


Registry names as URLs

The URL https://[HOSTNAME]/[PROJECT-ID]/[IMAGE] is a URL for that registry in the GCP Console. These links can be visited by any authenticated user who has permission to access the registry. See above for how to construct the registry name.

For example, the following URLs link to public registries in GCP Console:

Container image formats

Container Registry supports Docker Image Manifest V2 and OCI image formats.

For more information, refer to Container Image Formats.

Access control

Container Registry stores its tags and layer files for container images in a Cloud Storage bucket in the same project as the registry. Access to the bucket is configured using Cloud Storage's identity and access management (IAM) settings.

By default, project Owners and Editors have push and pull permissions for that project's Container Registry bucket. Project Viewers have pull permission only.

For more information, refer to Configuring Access Control.

See the Container Registry deprecation notices for information about plans to move image metadata out of Cloud Storage into a high-performance backend database.


You can use the gcloud docker -a command to configure Docker authentication with GCP credentials. Container Registry supports advanced authentication methods using access tokens or JSON key files.

Docker credential helper

Docker needs access to Container Registry to push and pull images. You can use the Docker credential helper command-line tool to configure your Container Registry credentials for use with Docker.

The credential helper fetches your Container Registry credentials, either automatically, or from a location specified using its --token-source flag, then writes them to Docker's configuration file. This way, you can use Docker's command-line tool, docker, to interact directly with Container Registry.

For more information, refer to Advanced Authentication.

Container Registry Service Account

When you enable the Container Registry API, Container Registry adds a service account to your project. This service account has the following name:


This Container Registry service account is designed specifically for Container Registry to perform its service duties on your project. Google owns this account, but it is specific to your project and is listed in the Service Accounts and IAM sections of the GCP Console.

If you delete this service account or change its permissions, certain Container Registry features will not work correctly. You should not modify roles or delete the account.


The mirror.gcr.io registry is a global Container Registry mirror for Docker Hub's official repositories.

Using the mirror can speed up pulls for Docker Hub repositories. When you use mirror.gcr.io, your client first attempts to pull Docker Hub official images from the Container Registry mirror.

For more information, refer to Using Container Registry and Docker Hub Mirror.


You can use Cloud Pub/Sub to get notifications about changes to your container images.

For more information, refer to Configuring Cloud Pub/Sub Notifications.

Using Container Registry with GCP

Compute Engine instances and Google Kubernetes Engine clusters can push and pull Container Registry images based on Cloud Storage scopes on the instances. Refer to Using Container Registry with GCP.

Images stored in Container Registry can be deployed to the App Engine flexible environment.

Continuous Delivery Tool Integrations

Container Registry works with several popular continuous delivery systems.

Using Container Registry with Third-Party Solutions

When you're developing your applications, you might like to use third-party cluster management, continuous integration, or other solutions outside of GCP. Container Registry can be integrated with these external services.

These solutions might not provide access to the gcloud command-line tool for authentication. In such cases, you can use docker login to authenticate directly with Container Registry. For more information, refer to Advanced Authentication.

Some third-party solutions, such Kubernetes, provide documentation for integrating with Container Registry.

For a complete list of third-party solutions that integrate with Container Registry, see Continuous Delivery Tool Integrations.

Bu sayfayı yararlı buldunuz mu? Lütfen görüşünüzü bildirin:

Şunun hakkında geri bildirim gönderin...

Container Registry