Configuring access control

This page describes permissions to control access to Container Registry.

After you have configured permissions, you can then configure authentication for Docker clients that you use to push and pull images.

If you use Container Analysis to work with container metadata, such as vulnerabilities found images, see the Container Analysis documentation for information about granting access to view or manage metadata.

Permissions for the Container Registry service account

The Container Registry Service Agent is a Google-managed service account that acts on behalf of Container Registry when interacting with Google Cloud services.

To enforce the security principle of least privilege, this service account is granted the Container Registry Service Agent role in projects where the Container Registry API was enabled after October 5, 2020. This role has the following permissions:

• Publish topics: pubsub.topics.publish
• Read storage object ACLs: storage.objects.getIamPolicy
• Read storage object data and metadata: storage.objects.get
• List storage objects in a bucket and read object metadata: storage.objects.list

Previously, the Container Registry service account was granted the Editor role. Since the Editor role grants permissions to create and delete most resources in a project, we recommend restricting permissions if your Container Registry service account has this role.

To verify the current permissions of your Container Registry service account, run the command:

gcloud projects get-iam-policy PROJECT-ID  \
--flatten="bindings[].members" \
--format='table(bindings.role)' \
--filter="bindings.members:[e-mail]"

Where

• PROJECT-ID is the Google Cloud project ID.
• PROJECT-NUMBER is the Google Cloud project number.

You can obtain the project ID and project number in the Google Cloud Console or with the following commands:

PROJECT=$(gcloud config get-value project)
echo $PROJECT && gcloud projects list --filter="$PROJECT" --format="value(PROJECT_NUMBER)"

To grant the Container Registry Service Agent role and revoke the Editor role:

1. Grant the Container Registry Service Agent role with the following command:

   gcloud projects add-iam-policy-binding PROJECT-ID \
   --member=serviceAccount:[e-mail] --role=roles/containerregistry.ServiceAgent
   

2. Revoke the Editor role with the following command:

   gcloud projects remove-iam-policy-binding PROJECT-ID \
   --member=serviceAccount:[e-mail] --role=roles/editor
   

Permissions to access Container Registry

All users, service accounts, and other identities that interact with Container Registry must have the appropriate Identity and Access Management (IAM) permissions for Cloud Storage storage.

IAM permissions

IAM permissions determine who can access resources. All users, service accounts, and other identities that interact with Container Registry must have the appropriate Cloud Storage permissions.

By default, Google Cloud uses default service accounts to interact with resources within the same project. For example, the Cloud Build service account can both push and pull images when Container Registry is in the same project.

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

Access scopes for VMs and clusters

For service accounts associated with Compute Engine VMs, including VMs in GKE clusters, access to storage is based on both IAM permissions and the configured storage access scope.

The Compute Engine default service account is configured to pull images in the same project as the VM. If you need a VM or GKE cluster to pull images or interact with Container Registry in a different project, see Using Container Registry with Google Cloud.

Configuring IAM permissions

Container Registry uses Cloud Storage buckets as the underlying storage for container images. You control access to your images by granting appropriate Cloud Storage permissions to a user, group, service account, or other identity.

Cloud Storage permissions granted at the project level apply to all storage buckets in the project, not just the buckets used by Container Registry. To configure permissions specific to Container Registry, grant permissions on the storage bucket used by the registry. Container Registry ignores permissions set on individual objects within the storage bucket.

Although you can also use the project-level roles Owner, Editor, and Viewer to grant access, the Cloud Storage roles enables you to apply the security principle of least privilege, so that users and service accounts only have the permissions that are required.

Google Cloud products and applications that interact with Google Cloud use service accounts to interact with Container Registry. The following considerations apply to service account access:

• By default, service accounts for some common integrations are configured with access to Container Registry within the same project. For example, by default the Cloud Build service account can push and pull images in the same project.
• If the service account needs to access Container Registry in another project, you must grant the required permissions in the project with Container Registry.
• VM instances, including those in Google Kubernetes Engine clusters, must have the correct storage access scopes configured to push or pull images. By default, VMs can pull images when Container Registry is in the same project.

Permissions and roles

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

Note: If you enable uniform bucket-level access for any storage bucket, make sure that all Container Registry users and service accounts have Cloud Storage roles explicitly set. In this case, the Owner and Editor roles by themselves might not grant the required permissions.

For more information about Cloud Storage roles and permissions, see the Cloud Storage documentation.

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 IAM permissions

Grant permissions on the storage bucket that Container Registry uses.

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

Granting permissions

1. Create a storage bucket for the multi-regional host if it does not already exist in your project. The available hosts are: gcr.io, asia.gcr.io, eu.gcr.io, and us.gcr.io. To perform this step, you must have Owner, Editor, or Storage Admin permissions.

   To create the storage bucket, push an initial image to the host. For example, these commands pull the busybox image from Docker Hub, tag it with the a path to the gcr.io registry in the project my-project, and then push the image.

   docker pull busybox
   docker tag busybox gcr.io/my-project/busybox
   docker push gcr.io/my-project/busybox
   

2. In the project with Container Registry, grant the appropriate permissions on the Cloud Storage bucket used by the host name.

   The bucket that stores your images has the name BUCKET-NAME of the form:

   • artifacts.PROJECT-ID.appspot.com for images pushed to a registry in the host gcr.io, or
   • STORAGE-REGION.artifacts.PROJECT-ID.appspot.com

   Where

   • PROJECT-ID is your Google Cloud Console project ID.
   • STORAGE-REGION is the location of the storage bucket:
     • 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 permission for a bucket using the Google Cloud Console or the gsutil command-line tool.

   Console

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

   2. Click the link artifacts.PROJECT-ID.appspot.com or STORAGE-REGION.artifacts.PROJECT-ID.appspot.com for the bucket.

      Here, PROJECT-ID is the Google Cloud project ID of the project that hosts Container Registry and STORAGE-REGION is the multi-region (asia, eu, or us) of the registry hosting the image.

   3. Select the Permissions tab.

   4. Click Add members.

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

      • a Google account (for example, [e-mail])
      • A Google group (for example, [e-mail])
      • an IAM service account
      • the Compute Engine default service account of another project. This account is used by the Google Kubernetes Engine to pull container image clusters by default. It is in the form [e-mail], where PROJECT-NUMBER is the Google Cloud project number of the project that is running the Google Kubernetes Engine cluster.

   6. From the Select a role drop-down menu, select the Storage category, and then select the appropriate permission.

      • Storage Object Viewer to pull images only
      • Storage Admin to push and pull images

   7. Click Add.

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

   gsutil

   1. Run the following command to list buckets in the project:

      gsutil ls
      

      The response looks like the following example:

      gs://[BUCKET_NAME1]/
      gs://[BUCKET_NAME2]/
      gs://[BUCKET_NAME3]/ ...
      

   2. Run the following command in your shell or terminal window:

      gsutil iam ch TYPE:EMAIL-ADDRESS:ROLE 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.
        • group, if the EMAIL-ADDRESS is a Google group.
      • EMAIL-ADDRESS can be one of the following:
        • a Google account (for example, [e-mail])
        • A Google group (for example, [e-mail])
        • an IAM service account
        • the Compute Engine default service account of another project. This account is used by Google Kubernetes Engine to pull container image clusters by default. It is in the form [e-mail], where PROJECT_NUMBER is the Google Cloud project number of the project that is running the Google Kubernetes Engine cluster.
      • ROLE is the Cloud Storage role you want to grant.
        • objectViewer to pull images
        • objectAdmin to push and pull images
      • BUCKET_NAME is the name of the Cloud Storage bucket in the form artifacts.PROJECT-ID.appspot.com or STORAGE-REGION.artifacts.PROJECT-ID.appspot.com

   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.

   Refer to the gsutil iam documentation for more information about the command.

3. Compute Engine and Google Kubernetes Engine are configured with permissions to pull images by default from Container Registry in the same project. If you have other requirements for these integrations, see Integration with Google Cloud services.

Configuring public access to images

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 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 Cloud 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 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://STORAGE-REGION.artifacts.PROJECT-ID.appspot.com, where:

   • PROJECT-ID is your Google Cloud Console project ID. Domain-scoped projects will have the domain name as part of the project ID.
   • STORAGE-REGION is the location of the storage bucket:
     • 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

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

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.

Revoking permissions

Use the following steps to revoke IAM permissions.

Console

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

2. Click the link artifacts.PROJECT-ID.appspot.com or STORAGE-REGION.artifacts.PROJECT-ID.appspot.com for the bucket. Here, PROJECT-ID is the Google Cloud project ID of the project that hosts Container Registry and STORAGE-REGION is the multi-region (asia, eu, or us) of the 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 an IAM service account
  • group:EMAIL-ADDRESS for a Google group.
  • allUsers for revoking public access
• BUCKET-NAME is the name of the desired bucket

Integration with Google Cloud services

By default, service accounts for some common integrations are configured for either pull or pull and push access within the same project. Access is based on IAM permissions, and you only need to configure permissions if the service account is connecting to Container Registry in a different project.

The service account associated with Compute Engine VM instances, including VMs in GKE clusters, has an additional requirement. VM access to storage is based on granted IAM permissions and storage access scopes.

• IAM permissions determine who can access a resources.
• Access scopes determine the default OAuth scopes for requests made through the gcloud tool and client libraries on a VM instance. As a result, access scopes can further limit access to API methods when authenticating with application default credentials.
  • To pull a private image, the VM service account must have read permission to the image's storage bucket.
  • To push a private images, the VM service account must have read-write, cloud-platform, or full-control permission to the image's storage bucket.

By default, the default Compute Engine default service account has Editor permission for resources in the same project and the read-only storage access scope. The read-only scope limits a VM to pulling images only. The default service account has the suffix @developer.gserviceaccount.com.

The following setups require you to change the default permission or scope configuration.

Pushing images from a VM or cluster

If you want to push images, the VM instance service account must have the storage-rw scope instead of storage-ro.

The VM and Container Registry are in separate projects

You must grant the service account with IAM permissions to access the storage bucket used by Container Registry.

Running gcloud commands on VMs

The service account must have the cloud-platform scope. This scope grants permissions to push and pull images, as well as run gcloud commands.

Steps to configure permissions and scopes are in the following sections.

Configuring IAM permissions for VMs

By default, Compute Engine VMs can only access storage in the same project. If your VM needs to access Container Registry in a different project, you must grant permissions to the VM service account.

1. In the project with your VM instance, get the name of the Compute Engine default service account or the service account you associated with the VM instance. The default service account has the suffix @developer.gserviceaccount.com.

2. In the project with the Container Registry, grant permissions so that the service account can access the Container Registry.

Configuring scopes for VMs

To set access scopes when creating a VM, use the --scopes option.

gcloud compute instances create INSTANCE --scopes=SCOPE

Where

• INSTANCE is the VM instance name.
• SCOPE is the scope you want to configure for the VM service account:
  • Pull images: storage-ro
  • Pull and push images: storage-rw
  • Pull and push images, run gcloud commands: cloud-platform

To change scopes for an existing VM instance:

Set the access scope with the --scopes option.

1. Stop the VM instance. See Stopping an instance.

2. Change the access scope with the following command.

   gcloud compute instances set-service-account INSTANCE --scopes=SCOPE
   

   Where

   • INSTANCE is the VM instance name.
   • SCOPE is the scope you want to configure for the VM service account:
     • Pull images: storage-ro
     • Pull and push images: storage-rw
     • Pull and push images, run gcloud commands: cloud-platform

3. Restart the VM instance. See Starting a stopped instance.

Configuring scopes for Google Kubernetes Engine clusters

By default, new GKE clusters are created with read-only permissions for Cloud Storage buckets.

To set the read-write storage scope when creating a Google Kubernetes Engine cluster, use the --scopes option. For example, the following command creates a cluster with the scopes bigquery, storage-rw, and compute-ro:

gcloud container clusters create example-cluster \
--scopes=bigquery,storage-rw,compute-ro

For more information about scopes you can set when creating a new cluster, refer to the documentation for the command gcloud container clusters create.

Note: Beginning with Google Kubernetes Engine version 1.10, gcloud and Cloud Console no longer grants the compute-rw access scope on new clusters and new node pools by default. Furthermore, if --scopes is specified in gcloud container create, gcloud no longer silently adds compute-rw or storage-ro. For more information about this change, see the GKE documentation.