How to grant access to the Google Container Registry

29 Mar, 2019
Xebia Background Header Wave

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]” for you, in which it stores your images you push to the domain “”. If you push to any of the regional registries the name will be “[REGION].artifacts.[PROJECT-ID]”. 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$PROJECT/nginx:latest
docker push$PROJECT/nginx:latest

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

gsutil ls gs://artifacts.$

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.$

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 ls gs://artifacts.$

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

Infrastructure as code

As you may know, at 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') | \
   docker build -t${var.project}/scratch:latest - && \
   docker push${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}”

 members = [
 depends_on = [“null_resource.docker-registry”]
resource “google_project_service” “containerregistry” {
 service            = “”
 disableondestroy = 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.

Mark van Holsteijn
Mark van Holsteijn is a senior software systems architect at Xebia Cloud-native solutions. He is passionate about removing waste in the software delivery process and keeping things clear and simple.

Get in touch with us to learn more about the subject and related solutions

Explore related posts