Create a trigger

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.

Requests to your service are triggered either by messages published to a Pub/Sub topic, when an audit log is created that matches the trigger's filter criteria, or in response to various events inside a Cloud Storage bucket—object creation, deletion, archiving, and metadata updates.

You can create triggers by using the gcloud command-line tool or through the Google Cloud Console.

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. To associate your trigger with a service account:

1. When creating your trigger, use the --service-account flag.
2. Update your trigger to have a service account.

Some of the steps in this document might not work correctly if your organization applies constraints to your Google Cloud environment. In that case, you might not be able to complete tasks like creating public IP addresses or service account keys. If you make a request that returns an error about constraints, see how to Develop applications in a constrained Google Cloud environment.

Create a trigger using gcloud

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

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

Cloud Audit Logs

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=google.cloud.audit.log.v1.written" \
    --event-filters="serviceName=SERVICE_NAME" \
    --event-filters="methodName=METHOD_NAME" \
    --service-account=[e-mail]

Replace the following:

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

  Cloud Audit Logs triggers for Eventarc are available in specific regions and in the global region, but are not available in dual-region and multi-region locations. To avoid any performance and data residency issues caused by a global trigger, we recommend that the location match that of the Google Cloud service that is generating events.

  If you specify the global location, you will receive events from all locations for which the event filters match. For example, by creating a global Eventarc trigger, you can receive events from resources such as Cloud Storage buckets in the EU and US multi-regions.

• DESTINATION_RUN_SERVICE is the name of the Cloud Run service that receives the events for the trigger. The service must be in the same region as the trigger, unless the trigger's location is global. 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 is 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_NAME is the identifier of the Google Cloud service.
• METHOD_NAME is the identifier of the operation.
• PROJECT_NUMBER is your Google Cloud project number.

Notes:

• These flags are required:
  • --event-filters="type=google.cloud.audit.log.v1.written"
  • --event-filters="serviceName=VALUE"
  • --event-filters="methodName=VALUE"
• For a list of the audit log events supported by Eventarc, including serviceName and methodName values, see Events supported by Eventarc.
• 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. See Determine event filters for Cloud Audit Logs.
• The --service-account flag is used to specify the Identity and Access Management (IAM) service account email associated with the trigger.
• Optionally, you can filter events for a specific resource by using the --event-filters="resourceName=VALUE" flag and specifying the complete path to the resource. Omit the flag for dynamically created resources that have identifiers generated at creation time.
• Optionally, you can 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.

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.audit.log.v1.written" \
      --event-filters="serviceName=storage.googleapis.com" \
      --event-filters="methodName=storage.buckets.update" \
      --event-filters="resourceName=projects/_/buckets/eventarc-bucket/objects/random.txt" \
      --service-account=${PROJECT_NUMBER}[e-mail]

This creates a trigger called helloworld-trigger for audit logs that are written by storage.googleapis.com and for the operation identified as storage.buckets.update.

Cloud Storage

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters="type=EVENT_FILTER_TYPE" \
    --event-filters="bucket=BUCKET" \
    --service-account=[e-mail]

Replace the following:

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

  Cloud Storage triggers for Eventarc are available in single-region, dual-region, and multi-region locations. Note that the trigger must be in the same location as the Cloud Storage bucket.

• DESTINATION_RUN_SERVICE is the name of the Cloud Run service that receives the events for the trigger. The service must be in the same region as the trigger, unless the trigger's location is global. 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 is 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.
• EVENT_FILTER_TYPE is the identifier of the Cloud Storage event and can be one of the following:
  • google.cloud.storage.object.v1.finalized—Event is sent when a new object is created (or an existing object is overwritten, and a new generation of that object is created) in the bucket
  • google.cloud.storage.object.v1.archived—Event is sent when a live version of an object is archived or deleted. This event is only sent for versioning buckets.
  • google.cloud.storage.object.v1.deleted—Event is sent when an object is permanently deleted. Depending on the object versioning setting for a bucket this means:
    • For versioning buckets, this is only sent when a version is permanently deleted (but not when an object is archived).
    • For non-versioning buckets, this is sent when an object is deleted or overwritten.
  • google.cloud.storage.object.v1.metadataUpdated—Event is sent when the metadata of an existing object changes.
• BUCKET is the globally unique identifier of the Cloud Storage bucket.
• PROJECT_NUMBER is your Google Cloud project number.

Notes:

• These flags are required:
  • --event-filters="type=EVENT_FILTER_TYPE"
  • --event-filters="bucket=BUCKET"
• Once a trigger is created, EVENT_FILTER_TYPE cannot be modified. Instead, create a new trigger and delete the old one.
• Events are delivered using Pub/Sub notifications from Cloud Storage. Setting up too many notifications registered against the same bucket might exhaust the notification limit for the bucket as indicated by the error Cloud Storage bucket ...: Pub/Sub notification limit reached. The bucket can have up to 10 notification configurations set to trigger for a specific event. See more quotas and limitations in the Cloud Storage quotas and limits page.
• 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 --service-account flag is used to specify the Identity and Access Management (IAM) service account email associated with the trigger.
• Optionally, you can 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.
• The Cloud Storage bucket must reside in the same Google Cloud project and region or multi-region as the Eventarc trigger.

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.storage.object.v1.finalized \
      --event-filters="bucket=my-project-bucket" \
      --service-account=${PROJECT_NUMBER}[e-mail]

This command creates a trigger called helloworld-trigger for the Cloud Storage bucket my-project-bucket and the event identified as google.cloud.storage.object.v1.finalized.

Existing Pub/Sub 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_NAME

Replace the following:

• TRIGGER is the ID of the trigger or a fully qualified identifier.
• LOCATION is 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.

• DESTINATION_RUN_SERVICE is the name of the Cloud Run service that receives the events for the trigger. The service must be in the same region as the trigger, unless the trigger's location is global. 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 is 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 is your Google Cloud project ID.
• TOPIC_NAME is the name of the existing Pub/Sub topic. The topic must be in the same project as the trigger.

Notes:

• The --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" flag is required.
• 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, you can 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 Manage subscriptions.

Example:

  gcloud eventarc triggers create pubsub-trigger-existing \
      --location=us-central1 \
      --destination-run-service=helloworld-events-pubsub \
      --destination-run-region=us-central1 \
      --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
      --transport-topic=projects/${PROJECT_ID}/topics/${TOPIC_NAME}

This creates a trigger called pubsub-trigger-existing for the Pub/Sub topic identified by projects/${PROJECT_ID}/topics/${TOPIC_NAME}.

New Pub/Sub 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"

Replace the following:

• TRIGGER is the ID of the trigger or a fully qualified identifier.
• LOCATION is 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.

• DESTINATION_RUN_SERVICE is the name of the Cloud Run service that receives the events for the trigger. The service must be in the same region as the trigger, unless the trigger's location is global. 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 is 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.

Notes:

• The --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" flag is required.
• 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, you can 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 Manage subscriptions.

Example:

  gcloud eventarc triggers create pubsub-trigger-new \
      --location=us-central1 \
      --destination-run-service=helloworld-events-pubsub \
      --destination-run-region=us-central1 \
      --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished"

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

As a best practice, we recommend not to reuse 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.

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

Create a trigger through the console

You can use the Cloud Console to create triggers with filters.

Note: You cannot create Cloud Storage triggers that do not use Cloud Audit Logs through the console. Use the gcloud tool instead.

1. In the Cloud Console, go to Cloud Run.
   

   Go to Cloud Run

2. From the list of services, click a service.

3. Click the Triggers tab, and click Add trigger.

4. In the Pick an event drop-down list, you can find all the services and events that are supported:

   

5. After selecting a service, you can choose an event.

   For example, select Cloud Storage > storage.objects.create.

   You must identify what event to filter. See Determine event filters for Cloud Audit Logs.

6. If you select the Cloud Pub/Sub topic event, you can select an existing topic or create a new topic for the trigger.

   By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Manage subscriptions.

7. For all other events, in the Full resource name field, you can optionally specify the complete path to the resource.

   For example, type projects/_/buckets/eventarc-bucket/objects/random.txt.

   Leave the field blank for dynamically created resources that have identifiers generated at creation time.

8. Pick a location to receive events from.

9. Configure which service account invokes your Cloud Run service, and specify the Service URL path to send the incoming request to.

   For Cloud Run destinations, this service account is used to generate identity tokens when invoking the service.

10. After creating the trigger, you can verify its health by ensuring that there is a checkmark on the Triggers tab.

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

What's next

• To get started using Eventarc, see the quickstarts.
• To deploy a Cloud Run service that receives events using Cloud Audit Logs, see Receive a Cloud Audit Logs event.
• To deploy a Cloud Run service that receives events using Pub/Sub, see Receive a Pub/Sub event.