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 routing to your Cloud Run
service that is triggered when an audit log is created that matches the
trigger's filter criteria. For a list of the audit log events supported by
Eventarc, including serviceName
and methodName
values, see
Google event types supported by Eventarc.
For more information about capturing events that are triggered when an audit log is created that matches the trigger's filter criteria, see Determine event filters for Cloud Audit Logs.
Prepare to create a trigger
Before you create a trigger, complete these prerequisites:
Console
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Enable the Cloud Logging, Eventarc, and Eventarc Publishing APIs.
If applicable, enable the API related to the Cloud Audit Logs events. For example, for Cloud Run functions audit logs, enable the Cloud Functions API.
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.
In the Google Cloud console, go to the Create service account page.
Select your project.
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
.Click Create and continue.
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.Click Continue.
To finish creating the account, click Done.
gcloud
In the Google Cloud console, 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.
Enable the Cloud Logging, Eventarc, and Eventarc Publishing APIs.
gcloud services enable logging.googleapis.com \ eventarc.googleapis.com \ eventarcpublishing.googleapis.com
If applicable, enable the API related to the Cloud Audit Logs events. For example, for Cloud Run functions audit logs, enable
cloudfunctions.googleapis.com
.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.
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.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.
Create a trigger
You can create an Eventarc trigger using the Google Cloud CLI or through the Google Cloud console.
Console
- In the Google Cloud console, go to the Eventarc Triggers page.
- Click Create trigger.
- 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.
- For the Trigger type, select Google sources.
- Select an Event provider.
This is the Google service that is the source of events through its audit logs. For example, select BigQuery.
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.
- In the Event type list, from the via Cloud Audit Logs events, select an event type.
- Select one of the following:
- Any resource—This is the default and includes dynamically created resources that have identifiers generated at creation time.
- Specific resource—You must provide the full resource name.
- Path pattern—You can
filter for resources using a path pattern.
For example, type
projects/_/buckets/eventarc-bucket/objects/random.txt
or typeprojects/_/buckets/**/r*.txt
.
- To specify the encoding of the event payload, in the Event data
content type list, select application/json or
application/protobuf.
Note that an event payload formatted in JSON is larger than one formatted in Protobuf. This might impact reliability depending on your event destination and its limits on event size. For more information, see Known issues.
- In the Region list, select a region.
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, Google recommends that the location match that of the Google Cloud service that is generating events. For more information, see Eventarc locations.
If you specify the global location, you will receive events from all locations yielding matches for the event filters. For example, by creating a global Eventarc trigger, you can receive events from resources in the EU and US multi-regions.
Note that there is a known issue with Cloud Audit Logs triggers for Compute Engine that results in events originating from a single region:
us-central1
. This is regardless of where the virtual machine instance is actually located. When creating your trigger, set the trigger location to eitherus-central1
orglobal
. - 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.
- In the Event destination list, select Cloud Run.
- 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. - 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
. - 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.
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" \ --event-data-content-type="EVENT_DATA_CONTENT_TYPE" \ --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 theeventarc/location
property; for examplegcloud 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, Google recommends that the location match that of the Google Cloud service that is generating events. For more information, see Eventarc locations.
If you specify the global location, you will receive events from all locations yielding matches for the event filters. For example, by creating a global Eventarc trigger, you can receive events from resources in the EU and US multi-regions.
Note that there is a known issue with Cloud Audit Logs triggers for Compute Engine that results in events originating from a single region:
us-central1
. This is regardless of where the virtual machine instance is actually located. When creating your trigger, set the trigger location to eitherus-central1
orglobal
.-
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_NAME
: the identifier of the Google Cloud serviceMETHOD_NAME
: the identifier of the operation
-
EVENT_DATA_CONTENT_TYPE
: (optional) the encoding of the event payload. This can beapplication/json
orapplication/protobuf
. The default encoding isapplication/json
.Note that an event payload formatted in JSON is larger than one formatted in Protobuf. This might impact reliability depending on your event destination and its limits on event size. For more information, see Known issues.
SERVICE_ACCOUNT_NAME
: the name of your user-managed service account.PROJECT_ID
: your Google Cloud project ID.
Notes:
These flags are required:
--event-filters="type=google.cloud.audit.log.v1.written"
--event-filters="serviceName=VALUE"
--event-filters="methodName=VALUE"
Optionally, 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. Or, filter events for a set of resources by using the--event-filters-path-pattern="resourceName=VALUE"
flag and specifying the resource path pattern.
- 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. - After a trigger is created, the event filter type can't be changed. For a different event type, you must create a new trigger.
- The
--service-account
flag is used to specify the Identity and Access Management (IAM) service account email associated with the trigger. - 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.
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=bigquery.googleapis.com" \
--event-filters="methodName=google.cloud.bigquery.v2.JobService.InsertJob" \
--service-account=${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
This creates a trigger called helloworld-trigger
for audit logs that are
written by bigquery.googleapis.com
and for the operation identified as
google.cloud.bigquery.v2.JobService.InsertJob
.
Terraform
You can create a trigger for a Cloud Run destination using Terraform. For details, see Create a trigger using Terraform.
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
In the Google Cloud console, go to the Eventarc Triggers page.
This page lists your triggers in all locations, and includes details such as names, regions, event providers, destinations, and more.
To filter your triggers:
- Click Filter or the Filter triggers field.
- 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.
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.