Configuring Access Control

This page describes the access control options available in Container Registry.

Container Registry uses a Cloud Storage bucket as the backend for serving container images. You can control who has access to your Container Registry images by adjusting permissions for the Cloud Storage bucket.

You manage access control in Cloud Storage by using the Console or the gsutil command-line tool. Refer to the gsutil acl and gsutil defacl documentation for more information.

Permissions and Roles

The following table explains the permissions and roles required for Container Registry actions.

Action Permissions Role Role Title
Push (Read and Write)

storage.buckets.create

storage.buckets.delete

storage.buckets.get

storage.buckets.list

storage.buckets.update

storage.objects.create

storage.objects.delete

storage.objects.get

storage.objects.list

storage.objects.update

roles/storage.admin Storage Admin
Pull (Read Only)

storage.objects.get

storage.objects.list

roles/storage.objectViewer Storage Object Viewer

Granting users and other projects access to a registry

To give specific users or container clusters running on other projects permissions to pull images from a registry, you need to grant read permission on the underlying Cloud Storage bucket. The bucket which backs your images will have a BUCKET_NAME of the form:

  • artifacts.[PROJECT-ID].appspot.com for images pushed to gcr.io/[PROJECT-ID], or
  • [REGION].artifacts.[PROJECT-ID].appspot.com, where [REGION] is:

    • us for registry us.gcr.io
    • eu for registry eu.gcr.io
    • asia for registry asia.gcr.io

To do so, perform the following steps:

gcloud

Run the following commands in your shell or terminal window:

gsutil iam ch  [TYPE]:[EMAIL-ADDRESS]:objectViewer gs://[BUCKET_NAME]

where:

  • [TYPE] can be one of the following:
    • serviceAccount, if [EMAIL-ADDRESS] specifies a service account.
    • user, if the [EMAIL-ADDRESS] is a Google account.
  • [EMAIL-ADDRESS] can be one of the following:
    • a Google account (for example, someone@example.com)
    • a Cloud IAM service account
    • the Compute Engine default service account of another project. This account is used by the Kubernetes Engine to pull container images clusters by default. It is in the form [PROJECT_NUMBER]-compute@developer.gserviceaccount.com, where [PROJECT-NUMBER] is the Cloud Platform project number of the project that is running the Kubernetes Engine cluster.
  • [BUCKET_NAME] is the name of the Cloud Storage bucket which hosts the images, as described above.

The gsutil iam ch command changes the IAM permissions of the storage bucket where the registry is hosted. Giving an account objectViewer permissions allows the account to pull images from the registry.

Console

  1. Visit the Cloud Storage page in GCP Console.
  2. Select the artifacts.[PROJECT-ID].appspot.com and/or [REGION].artifacts.[PROJECT-ID].appspot.com buckets' checkboxes. Here, [PROJECT-ID] is the Cloud Platform project ID of the project that hosts your Container Registry and [REGION] corresponds to the [REGION].gcr.io registry hosting the image.

  3. Click Show Info Panel.

  4. From the menu that appears, fill the Add members field with the email addresses of users needing read permission, separated by commas. This email address can be one of the following:

    • a Google account (for example, someone@example.com)
    • a Cloud IAM service account
    • the Compute Engine default service account of another project. This account is used by the Kubernetes Engine to pull container images clusters by default. It is in the form [PROJECT_NUMBER]-compute@developer.gserviceaccount.com, where [PROJECT-NUMBER] is the Cloud Platform project number of the project that is running the Kubernetes Engine cluster.
  5. From the Select a role drop-down menu's Storage category, select Storage Object Viewer.

  6. Click Add.

This procedure grants the user read permission for the whole bucket.

Serving images publicly

Each Container Registry is either entirely public or not. In a registry, it is not possible to publicly serve only specific images. If you have specific images you want to make public, create a new project to hold a publicly accessible Container Registry.

To serve container images publicly, make the repository's underlying storage bucket publicly accessible by following these steps:

  1. If your image you want to serve publicly is not in Container Registry, first, push it to the registry. There must be at least one image pushed to the registry for the underlying storage bucket to exist.

    To push an image, tag the image with the registry name:

    docker tag [SOURCE_IMAGE] [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
    

    then push the image to Container Registry:

    gcloud docker -- push [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]
    

    where:

    • [SOURCE_IMAGE] is the image's name on your local machine
    • [IMAGE] is the image name you want to apply in Container Registry
    • [HOSTNAME]is the gcr.io hostname
    • [PROJECT-ID] is your Google Cloud Platform Console project ID
    • [:TAG] is optional. If you don't specify a tag, docker will apply the default tag latest.
  2. Find the name of the Cloud Storage bucket for that registry. To do so, list the buckets:

    gsutil ls
    

    Your Container Registry bucket URL will be listed as gs://artifacts.[PROJECT-ID].appspot.com or gs://[REGION].artifacts.[PROJECT-ID].appspot.com.

  3. Make the storage bucket of the Container Registry publicly accessible by running the following command. This command will make all images in the registry publicly accessible.

    gsutil iam ch allUsers:objectViewer gs://[BUCKET_NAME]
    

    where:

    • gs://[BUCKET_NAME] is the Container Registry's bucket URL

Pulling a publicly accessible image

When the Container Registry is publicly accessible, anyone can pull its images by using:

docker pull [HOSTNAME]/[PROJECT-ID]/[IMAGE][:TAG]

where:

  • [IMAGE] is the image name in Container Registry
  • [HOSTNAME]is the gcr.io hostname
  • [PROJECT-ID] is the Google Cloud Platform Console project ID
  • [:TAG] is optional

Adding new project members with Cloud Storage permissions

You can add new project members to your Google Cloud Platform project and grant them the Storage Object Viewer role.

To add a new members to a project, perform the following steps:

  1. Visit the IAM & Admin page in GCP Console.
  2. Click Add and provide email addresses in the Members field.
  3. From the Roles drop-down menu's Storage category, select Storage Object Viewer.
  4. Click Add.

Revoking permissions for specific users

To revoke permissions for specific users, run the following command in your shell or terminal window, where [EMAIL-ADDRESS] is the user's email address and [BUCKET_NAME] is the name of the desired bucket:

gsutil acl ch -d [EMAIL-ADDRESS] gs://[BUCKET_NAME]

Send feedback about...

Container Registry