Configuring access control

This page describes the access control options available in Container Registry and how to use an encryption key with 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.

Caution: Container Registry only recognizes permissions set on the Cloud Storage bucket. Container Registry will ignore permissions set on individual objects within the Cloud Storage bucket.

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

Before you begin

Ensure you have pushed an image to Container Registry in the wanted host location (for example, asia.gcr.io). Container Registry creates a storage bucket when you push the first image to a host location, and you need this storage bucket to exist to be able to set permissions on it or set up an encryption key.

For more details about the host locations, see Registry name.

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 a registry in the host gcr.io, or

• [REGION].artifacts.[PROJECT-ID].appspot.com, where:

  • [PROJECT-ID] is your Google Cloud Platform Console project ID.
  • [REGION] is:
    • us for registries in the host us.gcr.io
    • eu for registries in the host eu.gcr.io
    • asia for registries in the host asia.gcr.io

You can grant read permission on the underlying Cloud Storage bucket using the Google Cloud Platform Console or the command line.

Console

1. Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.
2. Visit the Cloud Storage page in the GCP Console.

3. Click the artifacts.[PROJECT-ID].appspot.com and/or [REGION].artifacts.[PROJECT-ID].appspot.com bucket's link. Here, [PROJECT-ID] is the GCP project ID of the project that hosts your Container Registry and [REGION] corresponds to the [REGION].gcr.io registry hosting the image.

4. Select the Permissions tab.

5. Click Add members.

6. From the menu that appears, fill the 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, [e-mail])
   • a Cloud IAM service account
   • the Compute Engine default service account of another project. This account is used by the Google Kubernetes Engine to pull container images clusters by default. It is in the form [PROJECT_NUMBER][e-mail], where [PROJECT-NUMBER] is the GCP project number of the project that is running the Google Kubernetes Engine cluster.

7. From the Select a role drop-down menu's Storage category, select Storage Object Viewer.

8. Click Add.

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

Note: Email addresses and domains must be associated with an active Google Account or Google Apps account.

gsutil

1. Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.

2. Run the following command 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, [e-mail])
     • a Cloud IAM service account
     • the Compute Engine default service account of another project. This account is used by Google Kubernetes Engine to pull container images clusters by default. It is in the form [PROJECT_NUMBER][e-mail], where [PROJECT-NUMBER] is the GCP project number of the project that is running the Google 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.

Note: Email addresses and domains must be associated with an active Google Account or Google Apps account.

Serving images publicly

Container Registry is publicly accessible if the host location's underlying storage bucket is publicly accessible. Within a project, all images in each host location are either public or not. Within a project's host, it is not possible to publicly serve only specific images. If you have specific images you want to make public:

• Take care to keep them in a separate host location which you make public, or
• Create a new project to hold a publicly accessible images.

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

Console

1. Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.

2. Open the Container Registry page in the GCP Console.

   Open the Container Registry page

3. On the left panel, click on Settings.

4. On the Settings page under Public access, toggle the visibility to Public or Private. This setting controls the access to the underlying storage bucket.

   When the host's visibility is public, all images in your Google Cloud Platform project that are in that host location are publicly accessible.

gsutil

1. Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.

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, where:

   • [PROJECT-ID] is your Google Cloud Platform Console project ID. See Domain-scoped projects for how to work with projects IDs that include a domain.
   • [REGION] is:
     • us for registries in the host us.gcr.io
     • eu for registries in the host eu.gcr.io
     • asia for registries in the host asia.gcr.io

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

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

   where:

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

Note: Your project will be billed for the egress networking costs of serving the storage objects. Read Cloud Storage Pricing to learn more about egress traffic costs for Cloud Storage.

Pulling a publicly accessible image

When the Container Registry is publicly accessible, anyone can pull its images. For instructions, see Pulling images from a registry.

Using Customer-Managed Encryption Keys

You can use a Cloud Key Management Service encryption key with Container Registry by using the encryption key with the underlying storage bucket. To do so:

1. Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.

2. Follow the Cloud Storage instructions for Using Customer-Managed Encryption Keys with the storage bucket.

Revoking permissions

Console

1. Visit the Cloud Storage page in the GCP Console.

2. Click the artifacts.[PROJECT-ID].appspot.com and/or [REGION].artifacts.[PROJECT-ID].appspot.com bucket's link. Here, [PROJECT-ID] is the GCP project ID of the project that hosts your Container Registry and [REGION] corresponds to the [REGION].gcr.io registry hosting the image.

3. Select the Permissions tab.

4. Click the trash icon next to any member you wish to remove.

gsutil

Run the following command in your shell or terminal window:

gsutil iam ch -d [MEMBER] gs://[BUCKET_NAME]

where:

• [MEMBER] can be one of the following:
  • user:[EMAIL_ADDRESS] for a Google account
  • serviceAccount:[EMAIL_ADDRESS] for a Cloud IAM service account
  • allUsers for revoking public access
• [BUCKET_NAME] is the name of the desired bucket