Create triggers from Pub/Sub events

You can invoke Cloud Run services and functions by setting up a Pub/Sub trigger.

When configuring the trigger, you link the trigger to a specific Pub/Sub topic. This ensures your service or function is called automatically whenever a message is published to that topic.

You can configure this trigger in two ways:

  • Direct Pub/Sub trigger (Recommended): Route messages directly to your service or function using Pub/Sub. You manage the subscription directly, and your service or function receives the standard Pub/Sub push request. Use this if you need simpler configuration and lower latency.
  • Eventarc-based trigger: Route Pub/Sub messages to your service or function using Eventarc. You manage Pub/Sub triggers the same way as other Eventarc sources, and your service or function receives events as CloudEvents. Use this if you need Eventarc's advanced filtering or routing features.

Before you begin

  1. Make sure you have set up a new project for Cloud Run as described in the setup page.

  2. Enable the Artifact Registry, Cloud Build, Cloud Run Admin API, Cloud Logging, and Pub/Sub APIs:

    Enable the APIs

    If you are configuring an Eventarc-based trigger, you must also enable the Eventarc API:

    Enable the Eventarc API

Required roles

Grant the required IAM roles and permissions. If you are configuring an Eventarc-based trigger, see the required IAM roles and permissions for Eventarc.

Required roles for the deployer account

To get the permissions that you need to trigger from Pub/Sub events, ask your administrator to grant you the following IAM roles on your project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Note that by default, Cloud Build permissions include permissions to upload and download Artifact Registry artifacts.

Create a Pub/Sub trigger

Console

  1. In the Google Cloud console, go to the Cloud Run Services page:

    Go to Cloud Run

  2. Click the service or function you want to create a Pub/Sub trigger for.

  3. Select the Triggers tab.

    Select the tab for your selected trigger configuration:

    1. Click Add trigger, and select Pub/Sub trigger > Direct.
    2. In the Direct Pub/Sub subscription panel:
      • In the Cloud Pub/Sub topic field, select the topic if you have already created one, or click Create new topic to create a new topic.
      • In the Service account field, select the service account that the subscription uses to invoke your service. If the console lists missing roles, click Grant all.
      • For the Service URL path, enter the path on your service that should receive messages, such as / (default) or /pubsub. The console adds this path to your service's URL.
    3. Click Save.

    Eventarc

    In the Eventarc trigger pane, modify the trigger details as follows:

    1. Enter a name for the trigger in the Trigger name field, or use the default name.

    2. Select a Trigger type from the list:

      • Google Sources to specify triggers for Pub/Sub, Cloud Storage, Firestore, and other Google event providers.

      • Third-party to integrate with non-Google providers that offer an Eventarc source. For more information, see Third-party events in Eventarc.

    3. Select Pub/Sub from the Event provider list, to select a product that provides the type of event for triggering your function. For the list of event providers, see Event providers and destinations.

    4. Select google.cloud.pubsub.topic.v1.messagePublished from the Event type list. Your trigger configuration varies depending on the supported event type. For more information, see Event types.

    5. From the Select a Cloud Pub/Sub topic list, choose a topic for the trigger to monitor. Messages you publish to this topic trigger calls to your function.

    6. If the Region field is enabled, select a location for the Eventarc trigger. In general, the location of an Eventarc trigger should match the location of the Google Cloud resource that you want to monitor for events. In most scenarios, you should also deploy your function in the same region. See Understand Eventarc locations for more details about Eventarc trigger locations.

    7. In the Service account field, select a service account. Eventarc triggers are linked to service accounts to use as an identity when invoking your function. Your Eventarc trigger's service account must have the permission to invoke your function. By default, Cloud Run uses the Compute Engine default service account.

    8. Optionally, specify the Service URL path to send the incoming request to. This is the relative path on the destination service to which the events for the trigger should be sent. For example: /, /route, route, and route/subroute.

    9. Optionally, to enable retries if the delivery attempt fails, select the Enable retry on failure checkbox; otherwise, the default behavior is a single delivery attempt with no retries. For more information, see Retry events.

    10. After you've completed the required fields, click Save trigger.

gcloud

To create a trigger for your service or function using the gcloud CLI:

  1. Deploy your service or function if you haven't already done so.

  2. If you have an existing Pub/Sub topic, skip this step. Otherwise, create a Pub/Sub topic:

    gcloud pubsub topics create TOPIC_NAME

  3. Select the tab for your selected trigger configuration:

    Direct

    1. Configure the required roles for the Pub/Sub service agent:

      Required roles for the Pub/Sub service agent

      The following steps describe how to create and use a service account that can be used by the Pub/Sub subscription to invoke your service or function. These steps are required when using the Google Cloud CLI to create a Pub/Sub trigger command. If you are using the Google Cloud console to create the trigger, you can skip these steps.

      1. Create or select a service account to represent the Pub/Sub subscription identity.

             gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
        --display-name "Cloud Run Pub/Sub Invoker"

        Replace SERVICE_ACCOUNT_NAME with a name unique for your service account.

      2. Give the invoker service account permission to invoke your service:

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

        It can take several minutes for the IAM changes to propagate. In the meantime, you might see HTTP 403 errors in the service logs.

      3. Allow Pub/Sub to create authentication tokens in your project:

          gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
     --role=roles/iam.serviceAccountTokenCreator

        Replace the following:

        • PROJECT_ID: your Google Cloud project ID.
        • PROJECT_NUMBER: your Google Cloud project number.

        Project ID and project number are listed in the Project info panel in the Google Cloud console for your project.

    2. Create a Pub/Sub subscription with the service account:

      gcloud pubsub subscriptions create SUBSCRIPTION_NAME \
  --topic TOPIC_NAME \
  --ack-deadline=600 \
  --push-endpoint=SERVICE_URL/ \
  --push-auth-service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

      Replace the following:

      • SUBSCRIPTION_NAME: the name of the subscription you want to create.
      • TOPIC_NAME: the name of the topic you previously created.
      • SERVICE_URL: the HTTPS URL provided on deploying the service. This URL works even if you have also added a domain mapping.
      • SERVICE_ACCOUNT_NAME: the name of the service account you created earlier.
      • PROJECT_ID: your Google Cloud project ID.

      Notes:

      • The --push-auth-service-account flag activates the Pub/Sub push functionality for Authentication and authorization.

      • Your Cloud Run service domain is automatically registered for use with Pub/Sub subscriptions.

      • For Cloud Run only, there is a built-in authentication check that the token is valid and an authorization check that the service account has permission to invoke the Cloud Run service.

    Eventarc

    Run the following command to create a trigger that filters and routes events:

    gcloud eventarc triggers create TRIGGER_NAME  \
   --location=LOCATION \
   --destination-run-service=DESTINATION_RUN_SERVICE  \
   --destination-run-region=DESTINATION_RUN_REGION \
   --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
   --transport-topic=projects/PROJECT_ID/topics/TOPIC_NAME \
   --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Replace the following:

    • TRIGGER_NAME: the ID of the trigger or a fully qualified identifier.
    • LOCATION: the location of the Eventarc trigger. Alternatively, you can set the eventarc/location property; for example, gcloud config set eventarc/location us-central1.

      To avoid any performance and data residency issues, the location must match the location of the Google Cloud service that is generating events. For more information, see Eventarc locations.

    • DESTINATION_RUN_SERVICE: the name of the deployed service or Cloud Run function that receives the events for the trigger.
    • DESTINATION_RUN_REGION: (optional) the Cloud Run location in which the destination Cloud Run function can be found. If not specified, it is assumed that the function is in the same region as the trigger.
    • --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" flag is required and can't be changed. For a different event type, you must create a new trigger.
    • TOPIC_NAME: the ID of the existing Pub/Sub topic. The topic must be in the same project as the trigger.
    • SERVICE_ACCOUNT_NAME: the name of your user-managed service account.
    • PROJECT_ID: your Google Cloud project ID.

    Notes:

    • Optionally, to specify a single event delivery attempt with no retries, use the --max-retry-attempts flag. The only valid value is 1. If you omit the flag, the standard retry behavior applies. For more information, see Retry events.
    • Other flags are available. For more information, see gcloud eventarc triggers create.

Terraform

To create an Eventarc trigger for a Cloud Run function, see Create a trigger using Terraform.

Next steps