How to grant access to the Google Container Registry

Google Cloud provides a Docker image registry which you can use to store your private docker images. Although it is a separate Google service, there are no specific IAM roles associated with it, which allow you to control access to your registry. Instead, you use the Google Cloud Storage roles and permissions on the bucket that is implicitly created for you. In this blog we show you how you create the container registry storage bucket in your project and grant access to it.

Creating the storage bucket

GCR creates a bucket “artifacts.[PROJECT-ID].appspot.com” for you, in which it stores your images you push to the domain “gcr.io”. If you push to any of the regional registries the name will be “[REGION].artifacts.[PROJECT-ID].appspot.com”. The registry storage bucket will only be created, when you push a Docker image.


In order to push an image to your private docker registry, you need to authenticate first. There are several methods available, but the easiest one is to use the Google container registry credential helper for Docker. You install it by typing:

$ gcloud components install docker-credential-gcr
$ docker-credential-gcr configure-docker

Push an image

To create the underlying cloud storage bucket you need to push an image first. In this example, you push the latest NGiNX image to your private registry:

PROJECT=$(gcloud config --quiet get-value project)
docker pull nginx:latest
docker tag nginx:latest gcr.io/$PROJECT/nginx:latest
docker push gcr.io/$PROJECT/nginx:latest

After the image is pushed the registry storage bucket is created:

$ gsutil ls gs://artifacts.$PROJECT.appspot.com 

Granting access

When you read the access control documentation you will find that there are no specific IAM roles nor permissions associated with the Container Registry service. However, you can use IAM roles on the underlying storage bucket to set up access control.

To provide read access to the registry, you bind the “Storage Object Viewer” role to the identities you want to grant access. In this example the identity “allUsers” grants public read access:

$ gsutil iam ch allusers:objectViewer gs://artifacts.$PROJECT.appspot.com

Instead of granting public access, you could grant the role to a specific user, google group, service accounts or domain. To grant the permission to push images to the repository too, grant the Storage Object Admin role:

$ gsutil iam ch user:johndoe@binx.io:objectAdmin gs://artifacts.$PROJECT.appspot.com

Note that there is no way to control access to individual images in the project.

Infrastructure as code

As you may know, at binx.io we never do anything using the console, and avoid one-off CLI commands as we did above :-) We prefer infrastructure as code. So, add the following snippet to your terraform project and you will be ready to manage access to your Google Container Registry:

/* ensure that the image registry bucket is created by pushing an empty image to it */
resource "null_resource" "docker-registry" {
 provisioner "local-exec" {
  command = <<EOF
   gcloud components install docker-credential-gcr && \
   docker-credential-gcr configure-docker && \
   (echo 'FROM scratch'; echo 'LABEL maintainer=binx.io') | \
   docker build -t gcr.io/${var.project}/scratch:latest - && \
   docker push gcr.io/${var.project}/scratch:latest
 depends_on = ["google_project_service.containerregistry"]

resource "google_storage_bucket_iam_binding" "binding" {
 role   = "roles/storage.viewer"
 bucket = "artifacts.${var.project}.appspot.com"

 members = [

 depends_on = ["null_resource.docker-registry"]

resource "google_project_service" "containerregistry" {
 service            = "containerregistry.googleapis.com"
 disable_on_destroy = false


Google Cloud provides a private Docker Image Registry which you can use to store your own Docker images. You can grant access to your registry by binding either the “Storage Object Viewer” or “Storage Object Admin” to the underlying storage bucket, to provide read only, or read/write access respectively.

Picture of Mark van Holsteijn
Mark van Holsteijn