Create a trigger for third-party events

Preview — Third-party events in Eventarc

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

An Eventarc trigger declares your interest in a certain event or set of events. As a subscriber of events from third-party providers who offer an Eventarc source, you can configure event routing by specifying filters for the trigger including the event source, a destination, and a channel. The channel is a Google Cloud resource through which the provider interacts with a subscriber's project. By creating and activating a channel, you makes an explicit request to receive events from a provider. For more details, see Third-party events in Eventarc.

Requests to your service are triggered according to the event types set by the third-party provider. When triggered, Eventarc routes these events through Pub/Sub subscriptions to various destinations while managing delivery, security, authorization, observability, and error-handling for you.

You can create an Eventarc trigger by using the Google Cloud CLI.

Prepare to create a trigger

Depending on the destination you choose to send the events to, complete these prerequisites.

Cloud Run

1. Enable the APIs.
2. Grant the roles/eventarc.admin role to the user.
3. Create a service account and grant the required roles, permissions, and flags for authenticated and unauthenticated invocations.

GKE

1. Enable Workload Identity on your Google Kubernetes Engine cluster.
2. Enable the Eventarc API.
3. Grant the roles/eventarc.admin role to the user.
4. Create a service account.
5. Enable GKE destinations.

Workflows

1. Enable the APIs.
2. Grant the roles/eventarc.admin role to the user.
3. Create a service account.

For more information, follow the instructions when creating a trigger for a specific provider, event type, and destination and refer to the "Prepare to create a trigger" section.

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. However, for Cloud Audit Logs triggers, you can use the --event-filters-path-pattern flag and define a resource path pattern.

Cloud Run

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-run-service=DESTINATION_RUN_SERVICE \
    --destination-run-region=DESTINATION_RUN_REGION \
    --event-filters=type=EVENT_TYPE \
    --channel=CHANNEL_NAME \
    --project=PROJECT_ID \
    --service-account="MY_SERVICE_ACCOUNT@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.
• DESTINATION_RUN_SERVICE: 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: 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_TYPE: the type of event supported by the provider. For more information about listing available providers and retrieving information about supported event types, see List event providers.
• CHANNEL_NAME: a name for the channel. For more information, see Create a channel and retrieve its details.
• PROJECT_ID: your Google Cloud project ID.
• MY_SERVICE_ACCOUNT: the name of the IAM service account you created to which you granted specific roles required by Workflows.

Notes:

• 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.
• By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Subscription properties.

Example:

  gcloud eventarc triggers create helloworld-trigger \
      --location=us-central1 \
      --destination-run-service=helloworld-events \
      --destination-run-region=us-central1 \
      --event-filters=type=${EVENT_TYPE}\
      --channel=sample-channel \
      --project=${PROJECT_ID} \
      --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

This creates a trigger called helloworld-trigger for the specified event type supported by the third-party provider.

GKE

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-gke-cluster=DESTINATION_GKE_CLUSTER \
    --destination-gke-location=DESTINATION_GKE_LOCATION \
    --destination-gke-namespace=DESTINATION_GKE_NAMESPACE \
    --destination-gke-service=DESTINATION_GKE_SERVICE \
    --destination-gke-path=DESTINATION_GKE_PATH \
    --event-filters=type=EVENT_TYPE \
    --channel=CHANNEL_NAME \
    --project=PROJECT_ID \
    --service-account="MY_SERVICE_ACCOUNT@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.

• DESTINATION_GKE_CLUSTER: the name of the Google Kubernetes Engine (GKE) cluster in which the target GKE service that receives events is running.
• DESTINATION_GKE_LOCATION: the location in which the destination GKE service can be found. If not specified, it is assumed that the service is in the same region as the trigger. For more information see Knative serving locations.
• DESTINATION_GKE_NAMESPACE: the namespace in which the destination GKE service is running. If not specified, the default namespace is used.
• DESTINATION_GKE_SERVICE: the name of the GKE 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.
• (Optional) DESTINATION_GKE_PATH: the relative path you specify on the destination GKE service to which the events for the trigger should be sent. For example: /, /route, route, route/subroute.
• EVENT_TYPE: the type of event supported by the provider. For more information about listing available providers and retrieving information about supported event types, see List event providers.
• CHANNEL_NAME: a name for the channel. For more information, see Create a channel and retrieve its details.
• PROJECT_ID: your Google Cloud project ID.
• MY_SERVICE_ACCOUNT: the name of the IAM service account you created to which you granted specific roles required by Workflows.

Notes:

• --service-account: The IAM service account email your Eventarc trigger will use to invoke the workflow executions. We strongly recommend using a service account with the least privileges necessary to access the required resources. To learn more about service accounts, see Create and manage service accounts.
• Once a trigger is created, EVENT_FILTER_TYPE cannot be modified. Instead, create a new trigger and delete the old one.
• 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.
• By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Subscription properties.

Example:

  gcloud eventarc triggers create helloworld-trigger \
      --location=us-central1 \
      --destination-gke-cluster=gke-events-cluster \
      --destination-gke-location=us-central1-a \
      --destination-gke-namespace=default \
      --destination-gke-service=helloworld-events \
      --destination-gke-path=/ \
      --event-filters=type=${EVENT_TYPE} \
      --channel=sample-channel \
      --project=${PROJECT_ID} \
      --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

This command creates a trigger called helloworld-trigger for the specified event type supported by the third-party provider.

Workflows

gcloud eventarc triggers create TRIGGER \
    --location=LOCATION \
    --destination-workflow=DESTINATION_WORKFLOW \
    --destination-workflow-location=DESTINATION_WORKFLOW_LOCATION \
    --event-filters=type=EVENT_TYPE \
    --channel=CHANNEL_NAME \
    --project=PROJECT_ID \
    --service-account="MY_SERVICE_ACCOUNT@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.

• DESTINATION_WORKFLOW: the ID of the deployed workflow that receives the events from the trigger. The workflow can be in any of the Workflows supported locations and does not need to be in the same location as the trigger. However, the workflow must be in the same project as the trigger.
• DESTINATION_WORKFLOW_LOCATION (optional): the location in which the destination workflow is deployed. If not specified, it is assumed that the workflow is in the same location as the trigger.
• EVENT_TYPE: the type of event supported by the provider. For more information about listing available providers and retrieving information about supported event types, see List event providers.
• CHANNEL_NAME: a name for the channel. For more information, see Create a channel and retrieve its details.
• PROJECT_ID: your Google Cloud project ID.
• MY_SERVICE_ACCOUNT: the name of the IAM service account you created to which you granted specific roles required by Workflows.

Notes:

• --service-account: The IAM service account email your Eventarc trigger will use to invoke the workflow executions. We strongly recommend using a service account with the least privileges necessary to access the required resources. To learn more about service accounts, see Create and manage service accounts.
• 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.
• By default, Pub/Sub subscriptions created for Eventarc persist regardless of activity and do not expire. To change the inactivity duration, see Subscription properties.

Example:

  gcloud eventarc triggers create helloworld-trigger \
      --location=us-central1 \
      --destination-workflow=my-workflow \
      --destination-workflow-location=europe-west4 \
      --event-filters=type=${EVENT_TYPE} \
      --channel=sample-channel \
      --project=${PROJECT_ID} \
      --service-account="${TRIGGER_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

This creates a trigger called helloworld-trigger for the specified event type supported by the third-party provider.

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

What's next

• Learn more about Eventarc