Container Registry is a private container image registry that runs on Google Cloud. Container Registry supports Docker Image Manifest V2 and OCI image formats.
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 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.
- Integrate Container Registry with Google Cloud CI/CD services or your
existing CI/CD tools.
- Store artifacts from Cloud Build.
- Deploy artifacts 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 Container Analysis.
- Enforce deployment policies with Binary Authorization.
- Protect the registry in a VPC Service Controls security perimeter.
Registries
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 futureus.gcr.io
hosts the image in the United States, in a separate storage bucket from images hosted bygcr.io
eu.gcr.io
hosts the images in the European Unionasia.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 taglatest
. 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.
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.
Consider the following example:
us.gcr.io/builds/dev/web-app:beta-2.0
us.gcr.io/builds/stable/web-app:1.0
There are two images named web-app
in the project builds
. One is in a dev
repository and the other is in a stable
repository. This structure enables
you to store different versions of an image to support different stages of
development or different teams.
If needed, you can nest repositories. In this example, two separate products have a top level repository with child repositories beneath them.
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
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.
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 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 andrelease-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's 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 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
Registry names as URLs
The URL https://HOSTNAME/PROJECT-ID/IMAGE
is a URL for that registry in
the Cloud 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 Cloud 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.
Authentication
Before you can push or pull images, you must configure authentication. You
can configure Docker to use the gcloud
command-line tool 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 name:
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 owns this account, but it is specific to your project and is listed in the Service Accounts and IAM sections of the Cloud 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.
Pull-through cache
The mirror.gcr.io
registry caches frequently requested public images from the
official Docker Hub repositories.
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 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 Google Cloud. 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.
For a list of third-party solutions that integrate with Container Registry, see Continuous Delivery Tool Integrations.