Eventarc

Eventarc routes events from Google Cloud services to a destination such as a Cloud Run service. The GCP Data and ETL Blueprint uses one Eventarc trigger per stage to start the pipeline: every object written to the raw bucket becomes a request to the ETL trigger service.

What it does

An Eventarc trigger matches events by attributes, such as the event type and the bucket, and delivers each match to its destination as an HTTP request in CloudEvents format. Cloud Storage events travel over Pub/Sub, so the project's Cloud Storage service agent must be allowed to publish. The trigger delivers as a trigger service account, which must be allowed to invoke the destination and to receive events. An event whose delivery fails or times out is retried.

How BuiltForProd uses it

The trigger. <prefix>-raw-finalized (for example acme-usw1-prd-raw-finalized) matches the type google.cloud.storage.object.v1.finalized on the stage's raw bucket and delivers to the path / of the Cloud Run service <prefix>-etl-trigger. It lives in the bucket's location, the stage region, or the US multi-region when the lake uses it.

GCP/acme-gcp-blueprint-etl-infra/modules/cloud-run-trigger/eventarc.tf (lines 40-70)

resource "google_eventarc_trigger" "raw_finalized" {
  project  = var.project_id
  name     = "${var.name_prefix}-raw-finalized"
  location = local.event_location # the bucket's location (a regional bucket: the stage region)

  matching_criteria {
    attribute = "type"
    value     = "google.cloud.storage.object.v1.finalized"
  }

  matching_criteria {
    attribute = "bucket"
    value     = var.raw_bucket_name
  }

  destination {
    cloud_run_service {
      service = google_cloud_run_v2_service.trigger.name
      region  = var.gcp_region
      path    = "/"
    }
  }

  service_account = google_service_account.eventarc.email
  labels          = var.labels

  depends_on = [
    google_cloud_run_v2_service_iam_member.invoker,
    google_project_iam_member.eventarc_receiver,
  ]
}

Filtering. Eventarc filters on the bucket, not on an object prefix, so every object in raw produces an event; the trigger service itself accepts only input/*.json and ignores the rest.

Identities. The trigger identity sa-<prefix>-evt holds roles/run.invoker on the service and roles/eventarc.eventReceiver on the project, so delivery is authenticated and the service never allows unauthenticated calls. The data-lake unit grants the project's Cloud Storage service agent roles/pubsub.publisher, without which Eventarc delivers nothing; see Pub/Sub.

Retries. The service handles one event per instance and may wait for a free batch slot; if it is still waiting when the 300-second request timeout ends, Eventarc delivers the event again. See Dataproc Serverless for the batch limits.

Terms you will see

Term	Meaning
Eventarc trigger	The rule that matches events and names their destination.
object.finalized	The Cloud Storage event raised when an object write completes.
Trigger service account	sa-<prefix>-evt, the identity Eventarc delivers as.
Cloud Storage service agent	The Google-managed account that publishes the bucket's events.
Event receiver	The role that lets a trigger identity receive events.

Where to read more

• GCP Data and ETL Blueprint overview for the pipeline end to end.
• Cloud Run for the trigger service.
• Cloud Storage for the raw bucket and who may upload to it.