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

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.

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.

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.

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.

The flexible environment automatically builds your container images using Cloud Build and stores them in Container Registry.

Required permissions

If the VM instance you are using to push or pull images 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 VMs are in a different project or if the VMs use a different service account, you must grant the the service account 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.

Deploying to App Engine

You can deploy an image hosted by Container Registry to App Engine using the gcloud command-line tool.

You can use the gcloud beta app gen-config command in your image's root directory to automatically create the app.yaml file needed to deploy to App Engine. Alternatively, you can write the file yourself.

Once you have created the App Engine configuration file, built your Docker image, and pushed your image to Container Registry , you can 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.