This page lists the Identity and Access Management (IAM) predefined roles for accessing Cloud Run resources.
Predefined roles
The following table describes IAM roles that are associated with Cloud Run, and lists the permissions that are contained in each role.
Roles can be granted to users on an entire project or on individual Cloud Run resources. Read Managing access using IAM to learn more.
Roles only apply to Cloud Run resources, they don't apply to
Cloud Run domain mappings. The Project > Editor role
is needed to create or update domain mappings.
| Role | Permissions |
|---|---|
Cloud Run Admin( Full control over all Cloud Run resources. Lowest-level resources where you can grant this role:
|
|
Cloud Run Builder( Can build Cloud Run functions and source deployed services. |
|
Cloud Run Developer( Read and write access to all Cloud Run resources. Lowest-level resources where you can grant this role:
|
|
Cloud Run Editor( Editor role for Cloud Run |
|
Cloud Run Invoker( Can invoke Cloud Run services and execute Cloud Run jobs. Lowest-level resources where you can grant this role:
|
|
Cloud Run Viewer( Can view the state of all Cloud Run resources, including IAM policies. Lowest-level resources where you can grant this role:
|
|
Cloud Run Jobs Executor( Can execute and cancel Cloud Run jobs. |
|
Cloud Run Jobs Executor With Overrides( Can execute and cancel Cloud Run jobs with overrides. |
|
Cloud Run Service Invoker( Can invoke Cloud Run services. |
|
Cloud Run Source Developer( Deploy and manage Cloud Run source deployed resources. |
|
Cloud Run Source Viewer( View Cloud Run source deployed resources. |
|
Service agent roles
Service agent roles should only be granted to service agents.
| Role | Permissions |
|---|---|
Cloud Run Service Agent( Gives Cloud Run service account access to managed resources. |
|
For a reference describing the IAM permissions contained in each IAM role, refer to Cloud Run IAM permissions.
Custom roles
For developers that want to define their own roles containing bundles of permissions that they specify, IAM offers custom roles. Reference the additional configuration section and Cloud Run permissions page for specific permissions needed to run and manage Cloud Run resources.
Deployment permissions
Cloud Run resources run with a service identity.
To create or update Cloud Run resources, the deployer account must have access on the following resources:
- The Cloud Run resource
- The Artifact Registry repository of the Cloud Run resource's container image
- The service account used as the service identity
By default, the service identity is the Compute Engine default service account. However, Google recommends using a user-managed service account with the most minimal set of permissions. See the service identity configuration pages for services, jobs, and worker pools for more details.
Select the appropriate expander arrow to learn about the required deployment permissions.
Click to view the required roles for deploying a container
To get the permissions that you need to deploy a container, you or your administrator must grant IAM roles to the deployer account on the following resources:
- Cloud Run Developer
(
roles/run.developer) on the Cloud Run resource - Artifact Registry Reader
(
roles/artifactregistry.reader) on the Artifact Registry repository of the container images of the Cloud Run resource - Service Account User
(
roles/iam.serviceAccountUser) on the Cloud Run service identity
The following permissions are required to deploy services or revisions:
run.services.createto create services andrun.services.updateto update servicesrun.services.getandrun.operations.getto read the status of the serviceartifactregistry.repositories.downloadArtifactson the repository container the container images of the serviceiam.serviceAccounts.actAson the service identity
For permissions that are required to deploy, execute, or run other Cloud Run resources, see Cloud Run permissions.
Note that you can find these required permissions in other predefined roles, or use them to create a custom roles.
Click to view the roles for deploying from source
To get the permissions that you need to deploy a Cloud Run resource from source code, you or your administrator must grant the following roles:
- Cloud Run Source Developer
(
roles/run.sourceDeveloper) to the deployer account on your project. - Service Usage Consumer
(
roles/serviceusage.serviceUsageConsumer) on your project - Cloud Run Builder (
roles/run.builder) to the Compute Engine default service account on your project.
If your Cloud Run resource interfaces with Cloud Client Libraries, you must grant IAM roles to the service identity, as required by the Cloud Client Libraries.
If you are using a cross-project service account to deploy, execute, or run a
Cloud Run resource, grant the Service Account Token Creator
(roles/iam.serviceAccountTokenCreator) role on the service identity. See
Use service accounts in other projects
for more details.
To grant the Cloud Run deployer account access, see the following instructions:
Console
To grant access on the Cloud Run resource:
Go to the Cloud Run page in the Google Cloud console:
Select Services, Jobs, or Worker pools.
Click the checkbox at the left of the Cloud Run resource you want to add principals to.
In the information pane in the top right corner click the Permissions tab. If the information pane isn't visible, you may need to click Show Info Panel, then click Permissions.
Click Add principal.
In the New principals field, enter one or more identities that need access to your job.
From the Role drop-down menu, select a role or roles. The roles you select appear in the pane with a short description of the permissions they grant.
Click Save.
To grant access on the Artifact Registry repository:
Go to the Artifact Registry page in the Google Cloud console:
Click the checkbox at the left of the repository you want to add principals to.
In the information pane in the top right corner click the Permissions tab. If the information pane isn't visible, you may need to click Show Info Panel, then click Permissions.
Click Add principal.
In the New principals field, enter one or more identities that need access this repository.
From the Role drop-down menu, select Artifact Registry Reader.
Click Save.
To grant access on the service identity resource:
Go to the Service accounts page in the Google Cloud console:
Select the service account email address you are using as the service identity, either:
- The Compute Engine default service account:
PROJECT_NUMBER-compute@developer.gserviceaccount.com - A service account that was manually created:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
- The Compute Engine default service account:
Click the Permissions tab.
Click the Grant access button.
Enter the principal (e.g. user or group email) that matches the principal you're granting the Admin or Developer role to.
In the Select a role drop-down, select the Service Accounts > Service Account User role.
Click Save.
If you are deploying from source, grant access to the deployer account and the Cloud Build service account on your project:
Go to the IAM page in the Google Cloud console:
Select the email address of the principal you are using as the deployer account.
Click the edit icon on the left of the principal.
From the Role drop-down menu, select Cloud Run Source Developer.
From the Role drop-down menu, select Service Usage Consumer.
Click Save.
Select the service account email address you are using as the service identity, either:
- The Compute Engine default service account:
PROJECT_NUMBER-compute@developer.gserviceaccount.com - A service account that was manually created:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
- The Compute Engine default service account:
Click the edit icon on the left of the principal.
From the Role drop-down menu, select Cloud Run Builder.
Click Save.
gcloud
To grant access on the Cloud Run resource, use gcloud commands such as
gcloud run services add-iam-policy-bindingorgcloud run jobs add-iam-policy-binding, replacing the highlighted variables with the appropriate values:gcloud run CLOUD_RUN_RESOURCE_TYPE add-iam-policy-binding NAME \ --member="PRINCIPAL" \ --role="ROLE"
Replace the following:
- CLOUD_RUN_RESOURCE_TYPE: the Cloud Run
resource type, such as
services,jobs, orworker-pools. - NAME: the name of the Cloud Run resource.
PRINCIPAL: the deployer account you are adding the binding for, using the format
user|group|serviceAccount:emailordomain:domain. For example:user:test-user@gmail.comgroup:admins@example.comserviceAccount:test123@example.domain.comdomain:example.domain.com
ROLE with the role name to assign to the deployer account. For example,
roles/run.developer.
- CLOUD_RUN_RESOURCE_TYPE: the Cloud Run
resource type, such as
To grant access on the Artifact Registry repository, use the
gcloud artifacts repositories add-iam-policy-bindingcommand, replacing the highlighted variables with the appropriate values:gcloud artifacts repositories add-iam-policy-binding REPOSITORY \ --location="LOCATION" \ --member="PRINCIPAL" \ --role="roles/artifactregistry.reader"
Replace the following:
- REPOSITORY: the ID of the repository.
- LOCATION: the location of the repository.
- PRINCIPAL: the deployer account you are adding the
binding for, using the format
user|group|serviceAccount:emailordomain:domain.
To grant access on the service identity resource, use the
gcloud iam service-accounts add-iam-policy-bindingcommand, replacing the highlighted variables with the appropriate values:gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --member="PRINCIPAL" \ --role="roles/iam.serviceAccountUser"
Replace the following:
SERVICE_ACCOUNT_EMAIL: the service account email address you are using as the service identity, such as:
- The Compute Engine default service account:
PROJECT_NUMBER-compute@developer.gserviceaccount.com - A service account that was manually created:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
- The Compute Engine default service account:
PRINCIPAL: the principal you are adding the binding for, using the format
user|group|serviceAccount:emailordomain:domain. For example:user:test-user@gmail.comgroup:admins@example.comserviceAccount:test123@example.domain.comdomain:example.domain.com
If you are deploying from source, grant access to the deployer account and the Cloud Build service account on your project with the
gcloud projects add-iam-policy-bindingcommand.Grant the Cloud Run Builder role to the build service account on your project:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:BUILD_SERVICE_ACCOUNT_EMAIL \ --role=roles/run.builder
Replace the following:
- PROJECT_ID: your Google Cloud project ID.
BUILD_SERVICE_ACCOUNT_EMAIL: the service account email address you are using as the build service account, such as:
- The Compute Engine default service account (default):
PROJECT_NUMBER-compute@developer.gserviceaccount.com. - A service account that was manually created:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.
- The Compute Engine default service account (default):
Grant the Cloud Run Source Developer role to the deployer account on your project:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=PRINCIPAL \ --role=roles/run.sourceDeveloper
Replace the following:
- PROJECT_NUMBER: your Google Cloud project number.
- PROJECT_ID: your Google Cloud project ID.
- PRINCIPAL: the deployer account you are adding the binding for.
Grant the Service Usage Consumer role to the deployer account on your project:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=PRINCIPAL \ --role=roles/serviceusage.serviceUsageConsumer
Replace the following:
- PROJECT_NUMBER: your Google Cloud project number.
- PROJECT_ID: your Google Cloud project ID.
- PRINCIPAL: the deployer account you are adding the binding for.
For detailed instructions on how to find your project ID, and project number, see Creating and managing projects.
In addition to the deployer account needing these permissions, the Cloud Run service agent must have permissions to access the deployed container. By default, Google grants the Cloud Run Service Agent role to the Cloud Run service agent automatically.
Avoid IAM allow policy limits in automated deployments
When using Infrastructure-as-Code (IaC) tools like Config Connector to deploy Cloud Run services, the deployer account needs permission to read container images from Artifact Registry. These permissions are enforced by an IAM allow policy, which is attached to the relevant resource (Artifact Registry repository), and specifies which principals have been granted which roles.
If numerous Cloud Run services are deployed, each with a unique service account, IaC tools create individual role bindings in the Artifact Registry allow policy. This can quickly exceed the 1,500-member-per-policy limit, which restricts the number of principals (service accounts or users) listed in a single resource's allow policy.
To avoid this limitation, consider using a single service account across multiple services. This minimizes the number of entries in the Artifact Registry allow policy.
Optional permissions
The following optional permissions can be considered when configuring accounts with minimal permission set:
monitoring.timeSeries.liston the project level. Typically assigned through theroles/monitoring.viewerrole. It allows user to access metrics generated by their Cloud Run resource. For more information, go to the Cloud Monitoring documentation for Access Control.logging.logEntries.liston the project level. Typically assigned through theroles/logging.viewerrole. It allows user to access logs generated by their Cloud Run resource. For more information, go to the Access Control guide in the Cloud Logging documentation.