Container Registry is deprecated and scheduled for shutdown. Effective May 15, 2024, Artifact Registry hosts images for the gcr.io domain in projects without previous Container Registry usage. After March 18, 2025, Container Registry will be shut down.

To get started with managing containers on Google Cloud, use Artifact Registry. If you use Container Registry, learn how to transition to Artifact Registry to manage your containers on Google Cloud.

For more information on the deprecation and shutdown, see the deprecations page and release notes.

Using Container Registry with Google Cloud

To simplify your build and deployment workflows, some Google Cloud service accounts and runtime environments are pre-configured with permissions to access containers stored in the same project.

This page summarizes common integrations with Google Cloud products and the associated requirements to access containers.

General access requirements

By default, service accounts for some common integrations are configured with Cloud Storage permissions to access Container Registry within the same project.

For the service account used by Compute Engine VMs, including VMs in Google Kubernetes Engine clusters, access is based on both IAM permissions and storage access scopes.

You must configure or modify permissions yourself if:

You are using a service account in one project to access Container Registry in a different project
You are using a default service account with read-only access to storage, but you want to both pull and push images
You are using a custom service account to interact with Container Registry

Refer to the product-specific sections for additional information.

Cloud Build

By default, the Cloud Build service account has permissions to push and pull images when Container Registry is in the same project.

You must configure the appropriate permissions yourself in the following cases:

Cloud Build is in a different project than the repositories that you want the builds to access.
Your builds are using a service account other than the default Cloud Build service account. In this case, you must grant the service account permissions to access Container Registry.

Compute Engine

You can create VM instances using images stored in Container Registry.

Required permissions

If the VM instance and Container Registry are in the same Google Cloud project, the Compute Engine default service account is configured with permissions to pull images.

If the VM instance is in a different project or if the VM instance uses a different service account, you must grant the service account the appropriate permissions to access the storage bucket used by Container Registry.

By default, a Compute Engine VM has the read-only access scope configured for storage buckets. To push private Docker images, the VM instance must have the read-write storage access scope.

For details about permissions and access scopes, see Integrating with Google Cloud services.

Deploying images

When you create a VM you can deploy an image to it. To learn more, see the Compute Engine documentation for deploying containers and creating VM instance templates.

Container-optimized Compute Engine instances

For information about how to start a container-optimized Compute Engine instance using an image in your registry, see Starting a Docker container via cloud-config.

For additional information, see Creating and Configuring Instances.

Google Kubernetes Engine

Google Kubernetes Engine uses the service account configured on the VM instances of cluster nodes to push and pull images.

Required permissions

If the Google Kubernetes Engine cluster and the Container Registry storage bucket are in the same Google Cloud project, the Compute Engine default service account is configured with the appropriate permissions to push or pull images.

If the cluster is in a different project or if the VMs in the cluster use a different service account, you must grant the service account the appropriate permissions to access the storage bucket used by Container Registry.

By default, a Compute Engine VM has the read-only access scope configured for storage buckets. To push private Docker images, the VM instance must have the read-write storage access scope.

For details about permissions and access scopes, see Integrating with Google Cloud services.

Running an image

You can run a Container Registry image on a Google Kubernetes Engine cluster using the following command:

kubectl run [NAME] --image=[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]

where:

[NAME] is the name of the resource
[HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
[PROJECT-ID] is your Google Cloud console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
[IMAGE] is the image's name in Container Registry.
[TAG] is the tag that identifies the version of the image in Container Registry. If you do not specify a tag, Container Registry will look for the default tag latest.

For more information about Kubernetes commands, see Overview of kubectl.

Cloud Run

You can deploy images stored in Container Registry to Cloud Run.

Required permissions

To deploy to Cloud Run, you must have the Owner or Editor role, or both the Cloud Run Admin and Service Account User roles, or any custom role that includes this specific list of permissions.

Deploying images

To learn about deploying an image to Cloud Run, see the Cloud Run documentation.

App Engine Flexible Environment

You can use the App Engine Flexible Environment to customize an existing runtime (such as Java 8), or to provide your own runtime by supplying a custom Docker image or Dockerfile.

With Cloud Build, you can automate building your containers, pushing them to Container Registry, and deploying them to App Engine.

Required permissions

By default, the App Engine default service account has permissions to pull from and push to repositories in the same project.

If App Engine is in a different project, you must grant the App Engine service account with permissions to access your Container Registry repository.

Deploying to App Engine

You can deploy an image hosted by Container Registry to App Engine using the Google Cloud CLI.

Create the App Engine configuration file for your app.
Build a Docker image and push it to your repository. You can use Cloud Build to build and push your container to the repository.

Deploy your image to App Engine by running the following command:

gcloud app deploy --image-url=[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]

where:

[HOSTNAME] is listed under Location in the console. It's one of four options: gcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io.
[PROJECT-ID] is your Google Cloud console project ID. If your project ID contains a colon (:), see Domain-scoped projects.
[IMAGE] is the image's name in Container Registry.
[TAG] is the tag that identifies the version of the image in Container Registry. If you do not specify a tag, Container Registry will look for the default tag latest.