Creating 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, or when an audit log is created that matches the trigger's filter criteria.

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

Creating a trigger using gcloud

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

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. To avoid any performance and data residency issues caused by a global trigger, it should match the location of the Google Cloud service that is generating events. Alternatively, you can set the eventarc/location property; for example gcloud config set eventarc/location us-central1. For more information, see Eventarc locations.
  • 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 Managing 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.

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. To avoid any performance and data residency issues caused by a global trigger, it should match the location of the Google Cloud service that is generating events. Alternatively, you can set the eventarc/location property; for example gcloud config set eventarc/location us-central1. For more information, see Eventarc locations.
  • 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 Managing 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}.

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=PROJECT_NUMBER-compute@developer.gserviceaccount.com

Replace the following:

  • TRIGGER is the ID of the trigger or a fully qualified identifier.
  • LOCATION is the location of the Eventarc trigger. To avoid any performance and data residency issues caused by a global trigger, it should match the location of the Google Cloud service that is generating events. Alternatively, you can set the eventarc/location property; for example gcloud config set eventarc/location us-central1. For more information, see Eventarc locations.
  • 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 Determining 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}-compute@developer.gserviceaccount.com

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.

Creating a trigger through the console

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

  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:

    Adding a trigger through the console

  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 Determining 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 Managing 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.

What's next