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:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com"
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:
Grant the Container Registry Service Agent role with the following command:
gcloud projects add-iam-policy-binding PROJECT-ID \ --member=serviceAccount:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com --role=roles/containerregistry.ServiceAgent
Revoke the Editor role with the following command:
gcloud projects remove-iam-policy-binding PROJECT-ID \ --member=serviceAccount:service-PROJECT-NUMBER@containerregistry.iam.gserviceaccount.com --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.
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.
Granting permissions
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
, andus.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 thegcr.io
registry in the projectmy-project
, and then push the image.docker pull busybox docker tag busybox gcr.io/my-project/busybox docker push gcr.io/my-project/busybox
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 hostgcr.io
, orSTORAGE-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 hostus.gcr.io
eu
for registries in the hosteu.gcr.io
asia
for registries in the hostasia.gcr.io
You can grant permission for a bucket using the Google Cloud Console or the
gsutil
command-line tool.Console
- Visit the Cloud Storage page in the Cloud Console.
Click the link
artifacts.PROJECT-ID.appspot.com
orSTORAGE-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
, orus
) of the registry hosting the image.Select the Permissions tab.
Click Add members.
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,
someone@example.com
) - A Google group (for example,
my-developer-team@googlegroups.com
) - 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
PROJECT-NUMBER-compute@developer.gserviceaccount.com
, where PROJECT-NUMBER is the Google Cloud project number of the project that is running the Google Kubernetes Engine cluster.
- a Google account (for example,
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
Click Add.
gsutil
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]/ ...
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,
someone@example.com
) - A Google group (for example,
my-developer-team@googlegroups.com
) - 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
PROJECT_NUMBER-compute@developer.gserviceaccount.com
, wherePROJECT_NUMBER
is the Google Cloud project number of the project that is running the Google Kubernetes Engine cluster.
- a Google account (for example,
- ROLE is the Cloud Storage role you want to grant.
objectViewer
to pull imagesobjectAdmin
to push and pull images
- BUCKET_NAME is the name of the Cloud Storage
bucket in the form
artifacts.PROJECT-ID.appspot.com
orSTORAGE-REGION.artifacts.PROJECT-ID.appspot.com
- TYPE can be one of the following:
The
gsutil iam ch
command changes the IAM permissions of the storage bucket where the registry is hosted. Giving an accountobjectViewer
permissions allows the account to pull images from the registry.Refer to the
gsutil iam
documentation for more information about the command.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
Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.
Open the Container Registry page in the Cloud Console.
On the left panel, click on Settings.
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
Ensure you have pushed an image to Container Registry so that the underlying storage bucket exists.
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
orgs://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 hostus.gcr.io
eu
for registries in the hosteu.gcr.io
asia
for registries in the hostasia.gcr.io
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.
Revoking permissions
Use the following steps to revoke IAM permissions.
Console
- Visit the Cloud Storage page in the Cloud Console.
Click the link
artifacts.PROJECT-ID.appspot.com
orSTORAGE-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
, orus
) of the registry hosting the image.Select the Permissions tab.
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 accountserviceAccount:EMAIL-ADDRESS
for an IAM service accountgroup: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
, orfull-control
permission to the image's storage bucket.
- To pull a private image, the VM service account must have
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 ofstorage-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 rungcloud
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.
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.
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
- Pull images:
To change scopes for an existing VM instance:
Set the access scope with the --scopes option.
Stop the VM instance. See Stopping an instance.
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
- Pull images:
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.