Container Registry overview

Container Registry is the legacy service for storing private container images on Google Cloud.

The service is deprecated. You can move your existing images to Artifact Registry and continue to access them using gcr.io domain. Starting May 15, 2024, projects without previous Container Registry usage will only host images for the gcr.io domain in Artifact Registry.

For a comparison between Container Registry and Artifact Registry and information about transitioning from Container Registry to Artifact Registry, see Transitioning from Container Registry.

Working with your images

Many people use Docker Hub 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 Artifact Registry or Container Registry.

You can access the registry through secure HTTPS endpoints, which allow you to push, pull, and manage images from any system, VM instance, or your own hardware.

• Integrate the registry with Google Cloud CI/CD services or your existing CI/CD tools.
  • Store container images from Cloud Build.
  • Deploy container images to Google Cloud runtimes, including Google Kubernetes Engine, Cloud Run, Compute Engine, and App Engine flexible environment.
  • Identity and Access Management provides consistent credentials and access control.
• Secure your container software supply chain.
  • Manage container metadata and scan for container vulnerabilities with Artifact Analysis.
  • Enforce deployment policies with Binary Authorization.
• Protect the registry in a VPC Service Controls security perimeter.

Registries

You can create up to four multi-regional hosts in each Google Cloud project with Container Registry. If you want to create more discrete repositories with separate access policies or store images in regions instead of multi-regions, use Artifact Registry instead.

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/PROJECT-ID/IMAGE:TAG

or

HOSTNAME/PROJECT-ID/IMAGE@IMAGE-DIGEST

where:

• HOSTNAME is the location where the image is stored:

  • 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 within member states of the European Union
  • asia.gcr.io hosts the images in Asia

  These locations correspond to the multi-regions for Cloud Storage storage buckets. When you push an image to a registry with a new hostname, Container Registry creates a storage bucket in the specified multi-region. This bucket is the underlying storage for the registry. Within a project, all registries with the same hostname share one storage bucket.

• PROJECT-ID is your Google Cloud 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 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 "my-image".

• adding either :TAG or @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 the image my-image in the registry gcr.io/PROJECT-ID, you use this format to push or pull an image:

gcr.io/PROJECT-ID/my-image:tag1

where PROJECT-ID is your Google Cloud console project ID.

Caution: Only use registry commands to work with your stored images. Aside from configuring access control, avoid directly configuring or manipulating objects in Cloud Storage storage buckets used by Container Registry. Some Cloud Storage features such as object-level permissions and retention policies are unsupported. If these features are configured they might be ignored or cause issues.

Organizing images with repositories

You can group related images under a repository within a registry. When you tag, push, or pull an image, you specify the repository name under the project in the image path.

In Container Registry, repositories are an organization aid. They act like logical folders in the image path but do not reflect the actual file system structure or support more granular access control.

Consider the following images stored in the host us.gcr.io in the project builds:

us.gcr.io/builds/product1/dev/product1-app:beta-2.0
us.gcr.io/builds/product1/stable/product1:1.0
us.gcr.io/builds/product2/dev/product2:alpha
us.gcr.io/builds/product2/stable/product2:1.0

If a user has write access to the us.gcr.io host in the builds project, they have write access to any path under us.gcr.io/builds because all images are in the same storage bucket and you cannot restrict access at the repository or image level.

If you need more granular access control, you can use Artifact Registry, instead. In Artifact Registry, repositories are discrete resources, so you can apply separate IAM policies to repositories such us-docker.pkg.dev/builds/product1 and us-docker.pkg.dev/builds/product2.

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 tag or digest.

• Tags act as a label. You can apply multiple tags to an image. For example, an image might have the tag v1.5 for a version number and release-candidate to indicate readiness for final testing.
• 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.

To identify a specific version of the image my-image:

• add the image tag:

  gcr.io/PROJECT-ID/my-image:tag1
  

• or, add the image's digest:

  gcr.io/PROJECT-ID/my-image@sha256:4d11e24ba8a615cc85a535daa17b47d3c0219f7eeb2b8208896704ad7f88ae2d
  

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

In Google Cloud 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:

HOSTNAME/[DOMAIN]/[PROJECT]/IMAGE

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

gcr.io/example.com/my-project/image-name

Note: Scoping projects to a domain is a legacy feature. You cannot create new domain-scoped projects.

Registry names as URLs

The URL https://HOSTNAME/PROJECT-ID/IMAGE is a URL for an image in the Google Cloud console. Any authenticated user who has permission to access the registry host can use links to view any images it stores. See Registries for details on the image path format.

For example, the following URLs link to public registries in Google Cloud console:

• https://gcr.io/google-appengine/python
• https://gcr.io/google-containers/pause

Container image formats

Container Registry supports Docker Image Manifest V2 and OCI image formats. For more information, refer to Container Image Formats.

If you want to centrally store images and other types of artifacts, consider using Artifact Registry instead of Container Registry.

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.

A user who has access to a registry host can access any image in the host's storage bucket. If you need more granular access control, consider using Artifact Registry. Artifact Registry provides repository-level access control.

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 about Container Registry permissions, 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.

Authentication

Before you can push or pull images, you must configure authentication. You can configure Docker to use the Google Cloud CLI to authenticate requests to Container Registry. Container Registry also 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 the Docker 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 ID:

service-[PROJECT_NUMBER]@containerregistry.iam.gserviceaccount.com

This Container Registry service account is designed specifically for Container Registry to perform its service duties on your project. Google manages this account, but it is specific to your project.

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.

For more information about this service account and its permissions, see Container Registry service account.

Pull-through cache

The mirror.gcr.io registry caches frequently requested public images from Docker Hub.

Using cached images can speed up pulls from Docker Hub. Your client always checks for a cached copy of a Docker Hub image before attempting to pull it directly from Docker Hub.

For more information, refer to Pulling cached Docker Hub images.

Notifications

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

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

Using Container Registry with Google Cloud

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

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

Continuous delivery tool integrations

Container Registry works with popular continuous integration and continuous delivery systems including Cloud Build and third-party tools such as Jenkins.

Container Registry integrates seamlessly with Google Cloud services. For example, Cloud Build can push images to and pull images from Container Registry hosts in the same project by default. Runtime environments such as Google Kubernetes Engine and Cloud Run can also pull images from registry hosts in the same project by default.

Alternatively you can use third-party tools such as Jenkins to build, pull, and push your images. When using a third-party tool, you'll need to configure permissions and authentication for the account that will interact with Container Registry on behalf of the tool.

To explore examples of integrations, view Google Cloud technical guides that include Container Registry.