Eventarc and Pub/Sub Triggers for Cloud Run

Design for reliability and idempotent processing means building event handlers that stay consistent even when events are delivered more than once. A reliable handler treats each request independently, isolates failures so one service does not take down others, and uses storage that matches the required consistency level. Together these choices let instances scale, restart, and fail over without losing work.

1.1Stateless Service Design for Scalable Recovery

Stateless service design means each request is handled independent of previous requests with no required data held in instance memory. The stateless service depends on external persistence such as databases, queues, and files, so traffic flows from application clients to any available service instance and then from that instance to shared storage. Because no instance owns the conversation, the platform can add, remove, or restart instances without losing data needed to complete requests.

Statelessness is especially important with an autoscaler, because the instances, nodes, or pods hosting the service can be created and destroyed unexpectedly. When all services cannot be stateless, teams should state clearly which services require state and keep stateless and stateful services cleanly separated. This separation lets stateless services scale simply while stateful services use a more careful plan for availability and recovery.

1.2Preventing Cascading Failures Between Services

Preventing cascading failures means stopping the failure of one service from spreading to services that depend on it. As the network of services grows, service interdependencies also grow, and traffic that keeps flowing to an overloaded service can spread the outage. A service mesh (opens in a new tab) links services together and separates business logic from networking, providing resiliency features such as request retries, failovers, and circuit breakers.

Teams can reduce pressure on an overloaded service with three complementary patterns:

• Circuit breaker pattern opens the path to a failing service so callers stop sending traffic and the service has time to recover.
• Exponential backoffs retry failed requests with increasing delays so retries do not overwhelm the downstream service.
• Graceful degradation handles error states with reduced functionality so the overall app continues to serve clients.

These patterns increase resiliency either by giving overloaded services time to recover or by handling errors without passing failure to upstream callers.

1.3Choosing Storage for Consistency and Availability

Choosing storage for consistency and availability means matching the database model to what the service needs so storage does not limit scaling. Conventional relational databases offer transactions, strong consistency, referential integrity, and sophisticated querying, but they are typically hard to scale and need careful management for high availability. Non-relational NoSQL databases typically give up some relational features for greater availability and easier scalability, and under the CAP theorem they often choose availability over consistency.

Google Cloud also offers Spanner (opens in a new tab), a strongly consistent, highly available, and globally distributed database with SQL support. Choose a relational model when the service needs strong consistency and transactions, choose NoSQL when the data can be eventually consistent for greater availability and scalability, and consider Spanner when global distribution with strong consistency and SQL is needed. A cache further helps scalability by serving requests from memory, which lowers latency to disk-based storage and reduces load on downstream databases.

When the same data must exist in multiple locations, the replication choice controls consistency and conflict risk:

An Eventarc (opens in a new tab) trigger is a routing rule that listens for events and invokes a Cloud Run (opens in a new tab) service when a matching event occurs. The flow moves from an event source through Eventarc filtering to the Cloud Run destination, which receives the event as an HTTP POST request. This design keeps producers and consumers decoupled, so Cloud Run scales up only when events arrive.

2.1Event Sources, Providers, and Trigger Types

An Eventarc trigger is defined by its source category, event provider, and event type. The provider is the product that emits the event, such as Cloud Pub/Sub (Pub/Sub), Cloud Storage, or Firestore, and the event type is the specific action, such as google.cloud.pubsub.topic.v1.messagePublished. When a message is published to the selected Pub/Sub topic, the trigger causes Cloud Run to be called with that event data.

Trigger configuration starts by choosing one of three source categories:

• Google sources: triggers for Pub/Sub, Cloud Storage, Firestore, and other Google event providers.
• Custom: triggers for custom event sources built by your own applications.
• Third-party: triggers for non-Google providers that offer an Eventarc source.

After the category is selected, the provider list and event type list change to match that provider. The trigger location should be in the same Google Cloud region as both the monitored resource and the Cloud Run service to minimize latency and improve performance.

2.2Event Filtering and CloudEvents Structure

Event filtering in Eventarc selects which CloudEvents are delivered to Cloud Run based on exact attribute matches. A CloudEvents event is a standard structured envelope that carries attributes such as type alongside the event payload, so the Cloud Run service can process diverse sources in a consistent way. In configuration this appears as matching_criteria with an attribute of type and a value such as google.cloud.pubsub.topic.v1.messagePublished, or as an --event-filters flag on the command line.

The trigger also defines an event data content type of application/json or application/protobuf. A payload in JSON is larger than one in Protobuf, which can affect reliability depending on the destination and its limits on event size. Optional filters can narrow delivery further, for example to a specific bucket, topic, or API resource name.

2.3Routing Events to Cloud Run Services

A Cloud Run Eventarc trigger routes events from a Pub/Sub transport to a Cloud Run service destination. The transport identifies the Pub/Sub topic that Eventarc monitors, and the destination identifies the Cloud Run service name and region that receives the events. The destination service must be in the same project as the trigger and receives events as HTTP POST requests to its root URL path (/), unless a custom service path such as /route is configured.

Creating a Pub/Sub trigger for an existing Cloud Run service follows an ordered workflow:

1. Deploy the service: Deploy the Cloud Run service from a container or from source code.
2. Add the trigger: Open the service details, go to the Triggers tab, and add a Pub/Sub trigger.
3. Select provider and type: Choose Pub/Sub as the event provider and google.cloud.pubsub.topic.v1.messagePublished as the event type.
4. Select the topic: Choose the Pub/Sub topic to monitor, so publishing a message to that topic triggers calls to the service.
5. Set destination and identity: Confirm the Cloud Run destination, region, service account, and retry setting, then create the trigger.

Eventarc can create a new Pub/Sub topic for the trigger or reuse an existing topic specified as projects/PROJECT_ID/topics/TOPIC_ID. Retry on failure is enabled by default, so failed deliveries are retried; clearing the option limits delivery to a single attempt with no retries.

2.4Trigger Identity and Activation Lifecycle

Trigger identity and activation lifecycle describes which service account invokes Cloud Run and when the trigger becomes usable. The trigger service account must have permission to invoke the destination, which requires the Cloud Run Invoker role (roles/run.invoker). If no service account is selected, the trigger uses the Compute Engine default service account, formatted as PROJECT_NUMBER-compute@developer.gserviceaccount.com, and that account must also hold Pub/Sub Subscriber (roles/pubsub.subscriber) so the trigger can pull events from Pub/Sub.

A trigger moves through lifecycle states from inactive to active only after it is fully deployed. Saving the configuration only stores the rules, while deploying activates them, and it can take up to two minutes for a new trigger to become fully functional. After creation, the event filters cannot be edited in place; to change them, first create a new trigger and then delete the old one.

A Pub/Sub (opens in a new tab) push subscription for Cloud Run (opens in a new tab) is a configuration where Pub/Sub sends each published message as an authenticated HTTPS POST request to a Cloud Run service URL. Eventarc (opens in a new tab) manages this connection when a trigger of type google.cloud.pubsub.topic.v1.messagePublished links a Pub/Sub topic to a Cloud Run destination. The result is a decoupled, event-driven flow where publishers write to a topic and Cloud Run scales to handle each delivery without direct calls between components.

3.1How Push Delivery Reaches Cloud Run

Push delivery to Cloud Run follows an ordered path from topic to service with identity attached to each request. Data flows from the publisher to the Pub/Sub topic, then from the Pub/Sub subscription to the Cloud Run service endpoint as an HTTP request. Authentication travels with that request as an OpenID Connect (OIDC) token that identifies the trigger service account, and Cloud Run verifies the token before running the service code.

1. Publish: An application publishes a message to the Pub/Sub topic named in the trigger.
2. Push with identity: Pub/Sub creates a push request to the Cloud Run service URL and attaches an OIDC token minted for the trigger service account.
3. Verify and invoke: Cloud Run validates the OIDC token and checks that the trigger identity holds permission to invoke the service, then delivers the event to the root path / or a configured service URL path.

The Cloud Run service depends on the Pub/Sub topic and the Eventarc trigger to receive work, while the trigger depends on a valid service account and network reachability. For best performance, the trigger, the monitored topic, and the Cloud Run service should reside in the same Google Cloud region.

3.2Service Accounts for Push Trigger Identity

The trigger identity is the IAM service account that Eventarc uses when it invokes the Cloud Run service. The trigger sends requests under this identity, so Cloud Run applies its access checks to this account and not to the original publisher. If no account is selected, the trigger uses the Compute Engine default service account with the email format PROJECT_NUMBER-compute@developer.gserviceaccount.com.

A dedicated user-managed service account is recommended for production instead of the default account. The dedicated account follows least privilege by holding only the roles needed to publish, subscribe, and invoke, which limits the impact if credentials are misused. The default account is useful for testing, but organizations created after May 3, 2024 do not automatically grant it the Editor role because of the iam.automaticIamGrantsForDefaultServiceAccounts constraint.

3.3Authentication and Required IAM Roles

Authenticated delivery in Pub/Sub push relies on OIDC tokens and IAM permission checks at two trust boundaries. At the first boundary, the Pub/Sub service agent service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com must be able to mint OIDC tokens for the trigger identity. At the second boundary, Cloud Run must confirm that the trigger identity is allowed to call the service.

The following roles establish secure delivery from topic to service:

Reliable invocation of Cloud Run combines decoupled routing with secure identity and failure handling. Eventarc and Pub/Sub carry events from source to service, IAM roles and OIDC tokens prove the trigger identity at each trust boundary, and stateless design with retries and consistent storage lets the service handle duplicates and outages safely.

Key Facts

• An Eventarc trigger routes events from a Pub/Sub topic transport to a Cloud Run service destination that receives them as HTTP POST requests.
• Eventarc filtering uses exact attribute match only, and event source filters cannot be modified after the trigger is created.
• A trigger moves from inactive to active only after deployment, and a new trigger can take up to two minutes to become fully functional.
• A private Cloud Run service requires the trigger service account to hold Cloud Run Invoker (roles/run.invoker) for authenticated Pub/Sub push delivery.
• Transactionally synchronized data is immediately consistent in all locations, while asynchronously replicated data converges after a delay and may need conflict resolution.