Kiến Trúc Eventarc & Trigger Model

Trước khi đọc bất kỳ tài liệu cấu hình nào của Eventarc, cần xây dựng một mental model đúng về thứ nó thực sự là. Eventarc Standard không phải một event broker hay message queue. Nó là một managed event routing layer được xây trên Pub/Sub — một lớp mỏng đảm nhiệm việc đăng ký interest vào events từ GCP services, chuẩn hóa chúng thành CloudEvents format, và deliver đến destination.

Điểm cốt lõi nhất: Eventarc không xây transport infrastructure từ đầu. Toàn bộ reliability, retention, và retry semantics đến từ Pub/Sub. Eventarc chỉ là lớp orchestration phía trên.

Tại sao Eventarc tồn tại

Trước Eventarc, developer muốn react với GCP events (ví dụ: file upload lên Cloud Storage, API call ghi vào Cloud Audit Logs) phải tự wiring:

1. Cấu hình GCS notification → Pub/Sub topic thủ công
2. Tạo Pub/Sub subscription
3. Viết code pull/push subscription
4. Tự handle retry, ack deadline, dead letter
5. Tự handle authentication đến destination

Eventarc tự động hóa toàn bộ pipeline này và thêm ba thứ không thể tự làm được dễ dàng: chuẩn hóa format (CloudEvents), tích hợp IAM (trigger service account), và hơn 130 event sources có sẵn.

Internal Model: Trigger là gì

Một Eventarc trigger về mặt kỹ thuật là một tập hợp metadata được lưu trong Eventarc control plane, bao gồm:

• Filter criteria: event type, serviceName, methodName, resourceName (tùy provider)
• Destination: service URL, GKE service, Workflow
• Service account: danh tính dùng để authenticate khi gọi destination
• Transport topic: Pub/Sub topic được Eventarc tạo và quản lý

Khi bạn tạo trigger, Eventarc không chỉ lưu metadata — nó còn:

1. Tạo một Pub/Sub topic (nếu chưa có) phục vụ như transport
2. Tạo một Pub/Sub subscription trên topic đó
3. Wiring event source vào Pub/Sub topic bằng cách phù hợp với loại source

Sau khi trigger được tạo, sẽ mất tối đa 2 phút để nó bắt đầu nhận events — đây là thời gian propagation, không phải lỗi.

Hai đường ingest event

Eventarc Standard có hai con đường hoàn toàn khác nhau để event đến được Pub/Sub transport layer:

Đường 1: Cloud Audit Logs

GCP Service (Cloud Storage, BigQuery, GCE, ...)
    │
    ▼
Cloud Audit Logs (Admin Activity / Data Access)
    │
    ▼  [Eventarc đọc log entries, filter theo serviceName/methodName]
Pub/Sub Topic (managed by Eventarc)
    │
    ▼
Pub/Sub Subscription
    │
    ▼
Eventarc Delivery Agent
    │
    ▼
Destination (Cloud Run / GKE / Workflows)

Khi bạn tạo trigger với --event-filters="type=google.cloud.audit.log.v1.written", Eventarc lắng nghe Cloud Audit Logs và forward log entries khớp với serviceName và methodName bạn chỉ định vào Pub/Sub transport topic.

Đây là một điểm quan trọng cần hiểu: event không phải là Pub/Sub message từ đầu. Cloud Audit Logs là nguồn, Pub/Sub chỉ là transport intermediary do Eventarc quản lý.

Hệ quả quan trọng của đường Audit Log:

• Propagation delay tối đa 2 phút (audit log phải được ghi, filter, rồi mới forward)
• Chỉ capture Admin Activity và Data Access audit logs — không phải mọi action của mọi service
• Một số API calls không emit audit log — phải kiểm tra supported event types trước khi thiết kế

Đường 2: Direct Events (Pub/Sub, Cloud Storage, v.v.)

Cloud Storage / Firebase / Cloud Pub/Sub / ...
    │
    ▼  [Source service publish trực tiếp vào Pub/Sub topic]
Pub/Sub Topic (managed by Eventarc, hoặc existing topic)
    │
    ▼
Pub/Sub Subscription
    │
    ▼
Eventarc Delivery Agent
    │
    ▼
Destination

Với Direct events, source service (ví dụ Cloud Storage) publish notification trực tiếp vào Pub/Sub topic. Đây là cơ chế nhanh hơn và latency thấp hơn so với Audit Log path.

Với Pub/Sub source cụ thể:

# Eventarc có thể dùng existing topic hoặc tự tạo topic mới
gcloud eventarc triggers create my-trigger \
  --location=us-central1 \
  --destination-run-service=my-service \
  --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
  --transport-topic=projects/my-project/topics/existing-topic

Nếu không chỉ định --transport-topic, Eventarc tự tạo và quản lý topic. Pub/Sub subscriptions được Eventarc tạo không bao giờ expire do inactivity — khác với subscription bình thường có thể bị xóa sau 31 ngày không có message.

Filtering Mechanics

Filtering trong Eventarc Standard hoạt động tại tầng event metadata, không phải payload. Hai loại filter chính:

Filter cho Audit Log events

event-filters:
  - attribute: type
    value: google.cloud.audit.log.v1.written
  - attribute: serviceName
    value: storage.googleapis.com
  - attribute: methodName
    value: storage.objects.create

serviceName là API hostname của GCP service (ví dụ storage.googleapis.com, bigquery.googleapis.com). methodName là tên method trong Cloud Audit Log entry. Có thể dùng prefix matching cho resourceName để lọc theo bucket/project cụ thể:

--event-filters-path-pattern="resourceName=/projects/my-project/buckets/my-bucket/*"

Filter cho Direct events

event-filters:
  - attribute: type
    value: google.cloud.storage.object.v1.finalized
  - attribute: bucket
    value: my-bucket

Mỗi trigger chỉ có một tập filter. Muốn route cùng một event type đến nhiều destination khác nhau → cần nhiều trigger riêng biệt. Đây là giới hạn thiết kế của Standard mode — Advanced mode giải quyết bằng cơ chế bus/enrollment.

Giới hạn filter: Eventarc Standard hỗ trợ filter trên event type và một số attribute cố định. Không thể filter theo nội dung payload — đây là một trong những lý do Eventarc Advanced ra đời.

Destinations và cơ chế delivery tương ứng

Cloud Run

Đây là destination phổ biến nhất và đơn giản nhất về mặt cơ chế:

Eventarc Agent → HTTP POST → Cloud Run Service URL
                             (CloudEvents in binary mode)

Eventarc gọi Cloud Run service endpoint bằng HTTP POST với:

• CloudEvents context attributes trong HTTP headers (ce-id, ce-source, ce-type, v.v.)
• Event data trong HTTP body (JSON hoặc protobuf)
• Authorization header sử dụng token của trigger service account

Nếu Cloud Run service trả về 2xx, event được coi là delivered thành công. Non-2xx → retry theo policy của Pub/Sub subscription.

Cloud Functions (Gen2)

Cloud Functions Gen2 chạy trên Cloud Run nên delivery mechanism hoàn toàn giống Cloud Run. Function nhận HTTP request với CloudEvents format.

GKE

GKE destination là phức tạp nhất về cơ chế:

Pub/Sub Transport Topic
    │
    ▼  [StreamingPull]
gke-forwarder Pod (chạy trong GKE cluster, quản lý bởi Eventarc)
    │
    ▼  [HTTP POST]
Target GKE Service (ClusterIP hoặc external)

Với mỗi trigger pointing đến GKE destination, Eventarc deploy một gke-forwarder pod vào cluster. Pod này:

1. Mở StreamingPull connection đến Pub/Sub subscription
2. Nhận events từ Pub/Sub
3. Transform về CloudEvents format
4. Gửi HTTP POST đến target GKE service

gke-forwarder không phải một DaemonSet — nó là deployment được tạo riêng per-trigger. Điều này có nghĩa là nhiều trigger pointing đến cùng GKE cluster sẽ tạo nhiều forwarder pod.

Yêu cầu cho GKE destination:

• GKE cluster phải bật Workload Identity Federation
• Eventarc service account phải có quyền trên cluster
• Target service phải accessible từ trong cluster

Cloud Workflows

Eventarc Agent → Workflows API → Trigger new execution
                                  (event data làm argument)

Khi event được deliver, Eventarc gọi Workflows API để tạo một execution mới, truyền event data như input argument. Workflow sẽ nhận data này dưới dạng ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")} và có thể access event qua initial runtime argument.

Internal VPC HTTP Endpoints

Eventarc Standard hỗ trợ route events đến HTTP endpoint bên trong VPC network thông qua network attachment. Cơ chế này sử dụng Private Service Connect để Eventarc establish connection vào consumer VPC network mà không cần public IP.

IAM: Identity Flow trong Eventarc

IAM là một trong những phần hay bị hiểu sai nhất của Eventarc. Có hai danh tính liên quan:

1. Trigger Service Account

Service account bạn chỉ định khi tạo trigger. Đây là danh tính Eventarc dùng để gọi destination.

gcloud eventarc triggers create my-trigger \
  --service-account=eventarc-invoker@my-project.iam.gserviceaccount.com
  # ...

Quyền cần thiết cho service account này tùy theo destination:

Destination	Role cần thiết
Cloud Run	roles/run.invoker
Cloud Functions (Gen2)	roles/run.invoker
Workflows	roles/workflows.invoker
GKE	Cần additional Workload Identity setup

Service account này không cần quyền đọc event source. Nó chỉ cần quyền gọi destination.

2. Eventarc Service Agent

Đây là service account được Google tự động tạo cho project của bạn khi enable Eventarc API, với format:

service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com

Service agent này cần quyền:

• roles/eventarc.serviceAgent (built-in, được gán tự động)
• Với Audit Log triggers: quyền đọc từ Cloud Logging
• Với Pub/Sub transport: quyền publish vào transport topic

Lưu ý quan trọng: Khi dùng Audit Log triggers, bạn phải cấp thêm quyền cho service agent:

gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-eventarc.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

Nếu bỏ qua bước này, trigger sẽ được tạo thành công nhưng không có event nào được delivered.

Constraints và giới hạn thật

Giới hạn số lượng

• 500 triggers per project per region (Eventarc Standard)
• Mỗi trigger có một filter set duy nhất — không thể có multiple destinations cho một trigger
• Event size tối đa: 512 KB

Delivery timing

• Audit Log triggers: propagation delay tối đa 2 phút — event xảy ra lúc T, trigger có thể không fire cho đến T+2m
• Direct event triggers: delivery within seconds
• Không có in-order, FIFO delivery guarantee — kế thừa từ Pub/Sub semantics

Filter constraints

• Filter chỉ trên event metadata, không phải payload content
• resourceName filter: hỗ trợ exact match và path-pattern (prefix, suffix, glob với *)
• Không thể filter theo payload field (đây là use case cho Eventarc Advanced)

Trigger lifecycle

• Trigger được kích hoạt ngay khi tạo — không cần thêm bước nào
• Xóa trigger sẽ không tự động xóa Pub/Sub topic/subscription đã tạo
• Pub/Sub subscription của Eventarc không expire do inactivity

Anti-pattern: Nhầm Eventarc là event bus

Eventarc Standard là trigger-based router, không phải event bus. Sự khác biệt này có hệ quả thực tế:

Vấn đề: Bạn muốn 5 services khác nhau phản ứng với cùng một event type (ví dụ: file upload). Bạn nghĩ "tạo một trigger, route đến 5 destinations".

Thực tế: Không làm được trong Standard mode. Mỗi trigger chỉ có một destination. Bạn phải tạo 5 trigger riêng biệt với cùng filter criteria.

Vì sao thiết kế như vậy: Eventarc Standard được thiết kế cho use case đơn giản: "khi có event X, gọi service Y". Cho use case phức tạp hơn — fan-out, content-based routing, transformation — đó là lý do Eventarc Advanced tồn tại với bus/enrollment/pipeline model.

Hiểu sự khác biệt này từ đầu sẽ tránh thiết kế nhầm rồi phải refactor sau khi số trigger tăng lên.

References

• Eventarc Standard overview
• Eventarc triggers
• Supported event providers and destinations
• Route events to GKE destinations
• Route events to Cloud Workflows
• IAM for Eventarc