Route Cloud Pub/Sub events to Cloud Run

Standard

An Eventarc trigger declares your interest in a certain event or set of events. You can configure event routing by specifying filters for the trigger, including the event source, and the target Cloud Run service.

Eventarc delivers events to the event receiver in a CloudEvents format through an HTTP request.

These instructions show you how to configure event routing to your Cloud Run service that is triggered by a direct Cloud Pub/Sub event; in this case, a message published to a Pub/Sub topic. For more details, see the list of supported direct events.

Note: If both direct and audit log events are supported for a Google provider, we recommend that you create a trigger that filters for the direct event. Direct events offer a number of advantages over audit log events. For more information, see Event routes.

Prepare to create a trigger

Before you create a trigger, complete these prerequisites:

Console

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Enable the Cloud Logging, Eventarc, and Eventarc Publishing APIs.

   Enable the APIs

3. If applicable, enable the API related to the direct events. For example, for Cloud Pub/Sub events, enable the Cloud Pub/Sub API.

4. If you don't already have one, create a user-managed service account, then grant it the roles and permissions necessary so that Eventarc can manage events for your target service.

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account

   2. Select your project.

   3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for event trigger.

   4. Click Create and continue.

   5. To provide appropriate access, in the Select a role list, select the required Identity and Access Management (IAM) roles to grant to your service account for authenticated or unauthenticated invocations. For more information, see Roles and permissions for Cloud Run targets.

      For additional roles, click Add another role and add each additional role.

      Important: To accept authenticated invocations to your Cloud Run service, you must associate your trigger with a service account that has the roles/run.invoker role. When creating or updating your trigger, select that service account.

   6. Click Continue.

   7. To finish creating the account, click Done.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Enable the Cloud Logging, Eventarc, and Eventarc Publishing APIs.

   gcloud services enable logging.googleapis.com \
     eventarc.googleapis.com \
     eventarcpublishing.googleapis.com
   

3. If applicable, enable the API related to the direct events. For example, for Cloud Pub/Sub events, enable pubsub.googleapis.com.

4. If you don't already have one, create a user-managed service account, then grant it the roles and permissions necessary so that Eventarc can manage events for your target service.

   1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
      

      Replace SERVICE_ACCOUNT_NAME with the name of the service account. It must be between 6 and 30 characters, and can contain lowercase alphanumeric characters and dashes. After you create a service account, you cannot change its name.

   2. Grant the required Identity and Access Management (IAM) roles or permissions for authenticated or unauthenticated invocations. For more information, see Roles and permissions for Cloud Run targets.

   Important: To accept authenticated invocations to your Cloud Run service, you must associate your trigger with a service account that has the roles/run.invoker role. When creating or editing your trigger, use the --service-account flag to associate that service account with the trigger.

Create a trigger

You can create an Eventarc trigger using the Google Cloud CLI or through the Google Cloud console.

Note: Filtering is done through an exact match and does not support wildcards or regular expressions.

Console

1. In the Google Cloud console, go to the Eventarc Triggers page.

   Go to Triggers

2. Click Create trigger.
3. Type a Trigger name.

   This is the ID of the trigger and it must start with a letter. It can contain up to 63 lowercase letters, numbers, or hyphens.

4. For the Trigger type, select Google sources.
5. In the Event provider list, select Cloud Pub/Sub.

   Note that the event provider name used in the associated Google Cloud documentation might not have a prefix of Cloud or Google Cloud. For example, on the console, Memorystore for Redis is referred to as Google Cloud Memorystore for Redis.

6. In the Event type list, from the Direct events, select google.cloud.pubsub.topic.v1.messagePublished.
7. In the Select a Cloud Pub/Sub topic list, select a topic or accept the default of None so that a new topic is created for you.
8. In the Region list, select the same region as the Google Cloud service that is generating events.

   For more information, see Eventarc locations.

9. Select the Service account that will invoke your service or workflow.

   Or, you can create a new service account.

   This specifies the Identity and Access Management (IAM) service account email associated with the trigger and to which you previously granted specific roles required by Eventarc.

10. In the Event destination list, select Cloud Run.
11. Select a service.
    

    This is the name of the service that receives the events for the trigger. The service must be in the same project as the trigger and will receive events as HTTP POST requests sent to its root URL path (/), whenever the event is generated.

12. Optionally, you can 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, route/subroute.

13. Click Create.

After a trigger is created, the event source filters cannot be modified. Instead, create a new trigger and delete the old one. For more information, see Manage triggers.

gcloud

You can create a trigger by running a gcloud eventarc triggers create command along with required and optional flags.

Pub/Sub messages (existing topic)

gcloud eventarc triggers create TRIGGER \
  --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_ID \
  --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace the following:

• TRIGGER: 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.

  Pub/Sub triggers for Eventarc are only available in single-region locations, and you cannot create a global Eventarc trigger. For more information, see Eventarc locations.

• DESTINATION_RUN_SERVICE: the name of the Cloud Run service that receives the events for the trigger. The service can be in any of the Cloud Run supported locations and does not need to be in the same location as the trigger. However, the service must be in the same project as the trigger and will receive events as HTTP POST requests sent to its root URL path (/), whenever the event is generated.
• DESTINATION_RUN_REGION: (optional) the region in which the destination Cloud Run service can be found. If not specified, it is assumed that the service is in the same region as the trigger.
• PROJECT_ID: your Google Cloud project ID.

• TOPIC_ID: 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.

Notes:

• The --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.
• Each trigger can have multiple event filters, comma delimited in one --event-filters=[ATTRIBUTE=VALUE,...] flag, or you can repeat the flag to add more filters. Only events that match all the filters are sent to the destination. Wildcards and regular expressions are not supported.
• The --transport-topic flag is used to specify the ID of the existing Pub/Sub topic or its fully qualified identifier.
• Optionally, specify a relative path on the destination Cloud Run service to which the events for the trigger should be sent by using the --destination-run-path flag.
• By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Managing subscriptions.

Example:

gcloud eventarc triggers create helloworld-trigger \
  --location=us-central1 \
  --destination-run-service=helloworld-events \
  --destination-run-region=us-central1 \
  --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

This command creates a trigger called helloworld-trigger for the Pub/Sub topic identified by projects/${PROJECT_ID}/topics/${TOPIC_ID}.

Pub/Sub messages (new topic)

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

Replace the following:

• TRIGGER: 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.

  Pub/Sub triggers for Eventarc are only available in single-region locations, and you cannot create a global Eventarc trigger. For more information, see Eventarc locations.

• DESTINATION_RUN_SERVICE: the name of the Cloud Run service that receives the events for the trigger. The service can be in any of the Cloud Run supported locations and does not need to be in the same location as the trigger. However, the service must be in the same project as the trigger and will receive events as HTTP POST requests sent to its root URL path (/), whenever the event is generated.
• DESTINATION_RUN_REGION: (optional) the region in which the destination Cloud Run service can be found. If not specified, it is assumed that the service is in the same region as the trigger.
• SERVICE_ACCOUNT_NAME: the name of your user-managed service account.
• PROJECT_ID: your Google Cloud project ID.

Notes:

• The --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.
• Each trigger can have multiple event filters, comma delimited in one --event-filters=[ATTRIBUTE=VALUE,...] flag, or you can repeat the flag to add more filters. Only events that match all the filters are sent to the destination. Wildcards and regular expressions are not supported.
• Optionally, specify a relative path on the destination Cloud Run service to which the events for the trigger should be sent by using the --destination-run-path flag.
• By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Managing subscriptions.

Example:

gcloud eventarc triggers create helloworld-trigger \
  --location=us-central1 \
  --destination-run-service=helloworld-events \
  --destination-run-region=us-central1 \
  --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
  --service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

This command creates a new Pub/Sub topic and a trigger for it called helloworld-trigger.

As a best practice, Google recommends not reusing the Pub/Sub topic created by a trigger because deleting an Eventarc trigger also deletes any Pub/Sub topics that were created by the trigger.

Terraform

You can create a trigger for a Cloud Run destination using Terraform. For details, see Create a trigger using Terraform.

Note: Although your trigger is created immediately, it can take up to two minutes for a trigger to propagate and filter events.

List a trigger

You can confirm the creation of a trigger by listing Eventarc triggers using the Google Cloud CLI or through the Google Cloud console.

Console

1. In the Google Cloud console, go to the Eventarc Triggers page.

   Go to Triggers

   This page lists your triggers in all locations, and includes details such as names, regions, event providers, destinations, and more.

2. To filter your triggers:

   1. Click Filter or the Filter triggers field.
   2. In the Properties list, select an option to filter the triggers by.

   You can select a single property or use the logical operator OR to add more properties.

3. To sort your triggers, beside any supported column heading, click Sort.

gcloud

Run the following command to list your triggers:

gcloud eventarc triggers list --location=-

This command lists your triggers in all locations, and includes details such as names, types, destinations, and statuses.

What's next

• Learn more about Eventarc.
• Learn how to manage triggers.