Roles and permissions for Cloud Run functions targets

Standard

This document shows you how to grant Identity and Access Management (IAM) roles and permissions to support routing events from Google Cloud and other sources to Cloud Run functions using Eventarc.

Note: If you want to attach a service account in one project to an Eventarc trigger in another project, you must first complete the steps outlined in Support a cross-project service account.

1. Grant project-wide and deployment permissions to the principal creating triggers and deploying functions:

   1. The Eventarc Admin role gives you full control over all Eventarc resources, including specifying a service account for the trigger when you create it.

   2. The Service Account User role lets a principal impersonate and use a service account, including the trigger service account and the function runtime or build service accounts.

   3. Depending on how you deploy your function, the Cloud Run Source Developer and Service Usage Consumer roles (when deploying with the gcloud run CLI or Cloud Run Admin API) or the Cloud Functions Developer or Cloud Functions Admin role (when deploying with the gcloud functions CLI or Cloud Functions v2 API) let you create and update functions.

2. Grant Eventarc trigger permissions to the trigger service account: The Eventarc Event Receiver role lets your Eventarc trigger receive events from event providers. You don't need to grant the role if you are routing direct events from Cloud Pub/Sub.

3. Grant Cloud Run functions invocation permissions to the trigger service account: The Cloud Run Invoker role lets your Eventarc trigger invoke an authenticated Cloud Run function.

4. Grant permissions to Google service agents:

   1. The Eventarc Service Agent role lets the Eventarc service agent manage underlying transport resources and validate event sources. This role is granted by default when you create an Eventarc resource for the first time, but you must restore it if it is removed.

   2. If you are deploying functions with the gcloud functions CLI or Cloud Functions v2 API, the Cloud Functions Service Agent role lets the Cloud Functions service agent create and manage Eventarc triggers and underlying Cloud Run services. This role is granted by default when you enable the Cloud Functions API, but you must restore it if it is removed.

   3. If you are creating a trigger for direct events from Cloud Storage, grant the Pub/Sub Publisher role to the Cloud Storage service agent.

   4. If you enabled the Cloud Pub/Sub service agent on or before April 8, 2021, grant the Service Account Token Creator role to the Pub/Sub service agent.

For more information about granting IAM roles, see Manage access. You might also be able to get the required permissions through custom roles or other predefined roles.

Grant project-wide and deployment permissions

If you are the project creator, you are granted the basic Owner role (roles/owner). By default, this role includes the permissions necessary for full access to most Google Cloud resources. Otherwise, required roles must be granted by an administrator on the appropriate resource to the appropriate principal (also known as a member).

For example, a principal can be a Google Account (for end users) or a service account (for applications and compute workloads). Each principal has its own identifier, which is typically an email address.

1. The Eventarc Admin role (roles/eventarc.admin) gives you full control over all Eventarc resources.

   Grant the role on the project:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/eventarc.admin

   Replace the following:

   • PROJECT_ID: your Google Cloud project ID.

   • PRINCIPAL: an identifier for the trigger creator, which usually has the following form: PRINCIPAL_TYPE:ID. For example, user:[e-mail]. For a full list of the possible PRINCIPAL_TYPE values, see the Policy Binding reference.

2. The Service Account User role (roles/iam.serviceAccountUser) lets a principal run operations as a service account.

   You need this role so that you can associate a user-managed service account with an Eventarc trigger. You also need it so that you can act as the runtime service account when deploying a Cloud Run function, and as the build service account when deploying from source. For more information, see Roles for service account authentication.

   You can either grant the role on the project to let the principal impersonate multiple service accounts or grant the role on the service account to let the principal impersonate only a specific service account.

   Grant the role on the project:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=PRINCIPAL \
     --role=roles/iam.serviceAccountUser

   Or, grant the role on the service account:

   gcloud iam service-accounts add-iam-policy-binding \
     projects/SERVICE_ACCOUNT_PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_NAME@SERVICE_ACCOUNT_PROJECT_ID.iam.gserviceaccount.com \
     --member=PRINCIPAL \
     --role=roles/iam.serviceAccountUser

   Replace the following:

   • SERVICE_ACCOUNT_PROJECT_ID: the Google Cloud project ID that contains the service account.

   • SERVICE_ACCOUNT_NAME: the name of the service account.

3. Grant the roles required to deploy your Cloud Run function based on how you deploy it:

   • Deploying with gcloud run deploy or the Cloud Run Admin API: Grant the Cloud Run Source Developer role (roles/run.sourceDeveloper) and the Service Usage Consumer role (roles/serviceusage.serviceUsageConsumer) on the project. For more information, including required Cloud Build service account roles for building from source, see Required roles for deploying Cloud Run functions and Create a trigger for functions.

   • Deploying with gcloud functions deploy or the Cloud Functions v2 API: Grant the Cloud Functions Developer role (roles/cloudfunctions.developer) or the Cloud Functions Admin role (roles/cloudfunctions.admin) on the project. For more information, including required Cloud Build service account roles for building from source, see Additional configuration for deployment and Access control with IAM.

Grant Eventarc trigger permissions

Every Eventarc trigger is associated with an IAM service account at the time the trigger is created. You can specify a user-managed service account that the trigger uses as its default identity. If you don't specify a service account during the trigger's creation, the trigger uses the Compute Engine default service account for its identity.

Caution: For production environments, we strongly recommend creating a new service account and granting it one or more IAM roles that contain the minimum permissions required. You shouldn't use the default service account because it's automatically granted the highly privileged basic Editor role.

We recommend that you create your own user-managed service account to give you greater control and flexibility when managing your trigger.

1. Create a service account and note its name:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --description="DESCRIPTION" \
     --display-name="DISPLAY_NAME"

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account. This name appears in the email address that identifies the service account.

   • DESCRIPTION: an optional description of the service account.

   • DISPLAY_NAME: a service account name to display in the Google Cloud console.

2. Grant the Eventarc Event Receiver role (roles/eventarc.eventReceiver) on the project to the service account associated with your Eventarc trigger so that the trigger can receive events from event providers.

   Note that you don't need to grant the Eventarc Event Receiver role if you are routing direct events from Cloud Pub/Sub.

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/eventarc.eventReceiver

   Replace SERVICE_ACCOUNT_NAME with the name of your service account that you noted in the previous step.

Grant Cloud Run functions invocation permissions

By default, Cloud Run functions require authentication, which means that they can't be invoked without providing authentication credentials in the request. For projects with domain restricted sharing organization policies, use an authenticated target function rather than one that allows public (unauthenticated) access.

1. If you are routing events to an authenticated Cloud Run function, grant the Cloud Run Invoker role (roles/run.invoker) on the underlying Cloud Run service to the service account associated with your Eventarc trigger:

   gcloud run services add-iam-policy-binding FUNCTION_NAME \
     --region=REGION \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/run.invoker

   Replace the following:

   • FUNCTION_NAME: the name of your Cloud Run function.

   • REGION: the region where your function is deployed.

2. Optionally, you can grant the role on all Cloud Run services, functions, and jobs in a Google Cloud project. For more information, see Control access on all services and jobs in a project.

Note that if you create a trigger for an authenticated Cloud Run function without granting the Cloud Run Invoker role, the trigger is created successfully and is active. However, the trigger won't work as expected and a message similar to the following appears in the logs:

The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.

Grant permissions to Google service agents

Some Google Cloud services have service agents that let the services access your resources. If an API requires a service agent, then Google creates the service agent after you activate and use the API.

1. If the Eventarc Service Agent role (roles/eventarc.serviceAgent) was removed from the Eventarc service agent, grant the role on the project so that Eventarc can manage underlying transport resources and validate event sources. Otherwise, this role is granted by default when you create an Eventarc resource for the first time:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:[e-mail] \
     --role=roles/eventarc.serviceAgent

   Replace PROJECT_NUMBER with your Google Cloud project number. You can find your project number on the Welcome page of the Google Cloud console or by running the following command:

   gcloud projects describe PROJECT_ID --format='value(projectNumber)'

2. If you are deploying functions with gcloud functions deploy or the Cloud Functions v2 API and the Cloud Functions Service Agent role (roles/cloudfunctions.serviceAgent) was removed from the Cloud Functions service agent, grant the role on the project so that the service agent can create and manage Eventarc triggers and underlying Cloud Run services. Otherwise, this role is granted by default when you enable the Cloud Functions API:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:[e-mail] \
     --role=roles/cloudfunctions.serviceAgent

   Note that this role is deprecated and applies only to functions created using the Cloud Functions API. For functions created using Cloud Run, see the Cloud Run roles and permissions page.

3. If you are creating a trigger for direct events from Cloud Storage, to support publishing messages to a topic, grant the Pub/Sub Publisher role (roles/pubsub.publisher) on the project to the Cloud Storage service agent:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:[e-mail] \
     --role=roles/pubsub.publisher

4. If you enabled the Cloud Pub/Sub service agent on or before April 8, 2021, to support authenticated Pub/Sub push requests, grant the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) on the project to the Pub/Sub service agent. Otherwise, this role is granted by default:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:[e-mail] \
     --role=roles/iam.serviceAccountTokenCreator

What's next

• Learn about access control options in Eventarc.

• Learn how to trigger Cloud Run services and functions with events.

• Learn about access control with IAM for Cloud Run functions.

• Learn about best practices for using service accounts.

• Learn how to describe a trigger and verify its associated service account.