Cloud Run Source Deploys, Triggers and API Security

Deploying applications from source code is the automated path that turns application source files into a running Cloud Run (opens in a new tab) service without requiring a developer-written Dockerfile. Source code flows from the developer directory to Cloud Build (opens in a new tab) for image creation, then to Artifact Registry for storage, and finally to Cloud Run as a new revision. This path depends on both Cloud Build and Artifact Registry, so it is only available in regions supported by both services.

1.1How Buildpacks Turn Source Code into Containers

Google Cloud's buildpacks is an open-source system that converts source code into a runnable container image. A buildpack handles one part of the build, such as a language runtime, package manager, or web server, while builders group buildpacks into collections that inspect source code, create a build plan, and produce a production-ready image. Cloud Build runs this process remotely and pushes the finished image to Artifact Registry, which lets Cloud Run offer source-based deployment where the platform manages container creation.

1.2Language Detection and Dependency Handling

Language detection and dependency handling in buildpacks happen automatically from files in the source directory. The builder examines the source to identify the programming language, then installs libraries from the language package repository using its standard dependency file. The default builder can be extended with extra system packages, and a Procfile names the process to run when the container starts. The Procfile can override the default start process and is required for some runtimes including Python.

Supported source languages include Go, Node.js, Python, Java Spring Boot (opens in a new tab), Kotlin (opens in a new tab) and other JVM languages built with Maven or Gradle, .NET, Ruby, PHP, and an OS-only runtime.

1.3Building Images with Cloud Build and Pack

Building images with buildpacks can run remotely on Google Cloud or locally on a developer machine. Source code flows from the local source folder to the selected builder, then the built image flows to a container registry such as Artifact Registry where Cloud Run can deploy it later. The Artifact Registry Docker repository must already exist before the build, and the image reference uses the format LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.

A remote build follows an ordered workflow. First, change to the folder containing the application sources. Then run gcloud builds submit --pack image=IMAGE_URL with the target Artifact Registry image URL. Then wait for Cloud Build to run the builder, package the image, and push it to the registry.

1.4Artifact Registry and IAM Permissions for Source Deploys

Artifact Registry and Identity and Access Management (IAM) permissions control where generated images are stored and who can build them. Billing must be enabled and the Artifact Registry, Cloud Build, and Cloud Run Admin APIs must be enabled before deploying. The destination repository must already exist, and custom build worker pools (opens in a new tab) are supported for source deployments using --source, such as a VPC Service Controls secured build context, but not for image deployments using --image.

The deployer account and the build service account need separate grants. The deployer needs Cloud Run Source Developer (roles/run.sourceDeveloper) on the project to build and deploy from source, Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) to consume enabled APIs, and Service Account User (roles/iam.serviceAccountUser) on the Cloud Run service identity to act as that identity. The Compute Engine default service account used by Cloud Build, named PROJECT_NUMBER-compute@developer.gserviceaccount.com, needs Cloud Run Builder (roles/run.builder) on the project, and that grant can take a couple of minutes to propagate.

1.5Source-to-Service Deployment and Runtime Configuration

The source-to-service workflow moves code from a developer directory through build services into a Cloud Run revision. The core command is gcloud run deploy SERVICE --source ., which uploads a local directory, builds a container image with Cloud Build, stores the image in Artifact Registry, and creates a new revision that serves traffic. When a Dockerfile is present, the source is built with that Dockerfile, and when no Dockerfile is present, buildpacks detects the language and builds from a Google-managed secure base image. If neither --image nor --source is supplied, the deploy command defaults to source deployment.

With-build and no-build deployments are the two source paths, divided by whether Cloud Build creates the image. With-build deployment is the default and installs dependencies in the cloud. No-build deployment is a Preview path that uploads a pre-packaged archive directly to a Cloud Storage bucket and runs it on a selected base image, with no Cloud Build step. Choose no-build when speed matters and the archive is already self-contained, x86-compatible, 250 MiB or smaller, and uses a supported runtime with no Dockerfile, such as nodejs24 or the operating-system-only image osonly24. Dependencies must be installed locally before a no-build deployment.

Each revision bundles image and configuration together, so changing identity, environment variables, or resources creates a new revision. Build environment variables apply only during the Cloud Build image construction, while runtime environment variables and secrets apply to the running revision. A compose.yaml file can declare build directory, port mapping such as 8080:8080, environment variables, secrets, and volume mounts together for gcloud run compose up. The built container must respect the container contract by listening for HTTP requests on the port defined by the PORT environment variable that Cloud Run injects. By default Cloud Run waits for the startup probe to pass before routing traffic to a healthy revision, and that check can be disabled with --no-deploy-health-check for faster deploys.

Invoking Cloud Run services using triggers is the event-driven path where Eventarc (opens in a new tab) listens for events and calls a Cloud Run service only 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.1Stateless Design and Reliable Event Handling

Reliable event handling means building handlers that stay consistent even when events are delivered more than once. A stateless service handles each request independently with no required data held in instance memory, so traffic flows from clients to any available instance and then from that instance to shared storage such as databases, queues, and files. Because no instance owns the conversation, the platform can add, remove, or restart instances without losing work. Teams should keep stateless and stateful services cleanly separated so stateless services scale simply while stateful services use a more careful plan for availability.

Failures are contained with complementary resiliency patterns. The circuit breaker pattern stops sending traffic to a failing service so it has time to recover, exponential backoffs retry failed requests with increasing delays, and graceful degradation serves reduced functionality instead of passing failure upstream. Storage is matched to consistency needs: relational databases provide strong consistency and transactions but are harder to scale, NoSQL databases trade some relational features for availability and scalability, Spanner provides globally distributed strong consistency with SQL support, and a cache lowers latency and reduces load on downstream databases.

2.2Eventarc Triggers, Providers and Filtering

An Eventarc trigger is a routing rule defined by its source category, event provider, and event type. The provider is the product that emits the event, such as Cloud Pub/Sub (opens in a new tab), Cloud Storage, Firestore, or Firebase Remote Config, and the event type is the specific action, such as google.cloud.pubsub.topic.v1.messagePublished. Trigger configuration starts by choosing Google sources, custom sources built by your own applications, or third-party sources from non-Google providers, and the provider and event type lists then change to match that category.

Event filtering in Eventarc selects which CloudEvents are delivered based on exact attribute matches. A CloudEvents event is a standard envelope that carries attributes such as type alongside the payload, so the service can process diverse sources consistently. 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 gcloud CLI (opens in a new tab). The trigger also defines a payload encoding of application/json or application/protobuf, where JSON is larger and can affect reliability against destination size limits. The trigger, the monitored resource, and the destination service should be in the same region to reduce latency.

2.3Routing Events and Push Delivery to Cloud Run

Routing events to Cloud Run is the path that sends each matched event from the event source 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 the root path / unless a custom path such as /route is configured.

Creating a Pub/Sub trigger for an existing service follows an ordered workflow. First, deploy the Cloud Run service from a container or from source. Then open the service details, go to the Triggers tab, and add a Pub/Sub trigger. Then choose Pub/Sub as the provider and google.cloud.pubsub.topic.v1.messagePublished as the event type. Then select the topic to monitor, either by creating a new topic or reusing an existing topic such as projects/PROJECT_ID/topics/TOPIC_ID. Then confirm the destination, region, service account, and retry setting and create the trigger. Retry on failure is enabled by default, so clearing the option limits delivery to a single attempt.

Push delivery carries identity with each request. Data flows from the publisher to the Pub/Sub topic, then from the subscription to the Cloud Run endpoint as an HTTPS POST with an OpenID Connect (OIDC) token minted for the trigger service account. Cloud Run verifies the token and checks permission to invoke the service before running the code.

2.4Authentication and IAM Roles for Invocation

Authenticated invocation means the trigger calls Cloud Run under an IAM service account that Cloud Run verifies before routing to application code. If no account is selected, the trigger uses the Compute Engine default service account PROJECT_NUMBER-compute@developer.gserviceaccount.com. A dedicated user-managed service account is recommended for production because it follows least privilege, while the default account is useful for testing.

The following roles establish secure delivery from topic to service. The trigger service account needs Cloud Run Invoker (roles/run.invoker) on the destination service to invoke it and Pub/Sub Subscriber (roles/pubsub.subscriber) to pull events from Pub/Sub. The publishing identity needs Pub/Sub Publisher (roles/pubsub.publisher) on the topic to enter messages into the transport. The Pub/Sub service agent service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com needs Service Account Token Creator (roles/iam.serviceAccountTokenCreator) to mint OIDC tokens for authenticated push in older projects. A trigger moves from inactive to active only after deployment, and a new trigger can take up to two minutes to become fully functional.

Configuring event receivers is the setup that lets a Cloud Run service safely accept events from Eventarc (opens in a new tab) and Cloud Pub/Sub as authenticated HTTP requests. In this system Eventarc uses an IAM service account as the trigger identity, Pub/Sub carries the event, and Cloud Run verifies the caller before passing the request to application code. Each hop is protected by a separate role grant, so publishing, pulling, and invoking are authorized independently.

3.1Security and Trigger Identity for Event Receivers

Trigger identity is the IAM service account that Eventarc uses when it invokes the Cloud Run event receiver. If no account is selected, the trigger falls back to the Compute Engine default service account. That default account is acceptable for testing, but production must use a dedicated user-managed service account with only the minimum permissions it needs. The person who creates the trigger also needs setup permissions that are separate from runtime delivery, typically including Cloud Run Source Developer, Logs View Accessor, Project IAM Admin, Service Account Admin, Service Account User, and Service Usage Admin.

Default service accounts no longer receive broad access automatically in newer organizations. The organization policy constraint iam.automaticIamGrantsForDefaultServiceAccounts blocks automatic Editor grants for organizations created after May 3, 2024, so teams must grant less-permissive roles explicitly and can use Policy Simulator to check impact before removing Editor. A secure receiver is configured in dependency order: first create a dedicated service account, then grant least-privilege runtime roles, then attach the same account as the Cloud Run service identity and as the Eventarc trigger service_account, then create the trigger with authenticated delivery.

3.2Eventarc Routing and Filter Rules

Eventarc routing rules connect an event source to a Cloud Run destination through filters, transport, and identity. The trigger definition holds the source, the filters, the destination service, and the identity used to invoke that service. Traffic flows from the source to the Eventarc trigger, then from the trigger to the destination service over HTTPS as a POST to the root path / by default or to a configured path such as /route.

Trigger types define where events come from. Google sources cover providers such as Pub/Sub, Cloud Storage, Firestore, Firebase Remote Config (opens in a new tab), and Audit Logs. Custom sources cover customer-published events, while third-party sources cover non-Google providers with an Eventarc source. Event filters are exact-match rules on attributes such as type, resource name, and service, with no wildcard or regular expression support. Core criteria include the CloudEvents type such as google.cloud.pubsub.topic.v1.messagePublished, the monitored resource such as a specific topic or bucket, region alignment in the same region, and payload encoding as application/json or application/protobuf.

3.3Pub/Sub Messaging and Delivery Models

Cloud Pub/Sub messaging is the asynchronous system that decouples event producers from event receivers. Publishers broadcast events to a named topic channel, and subscribers react to events from that topic without publishers knowing how or when processing happens. Because publishers and subscribers interact only through the topic, many publishers and many subscribers can join independently. Pub/Sub uses per-message parallelism by leasing individual messages and tracking whether each message is processed, rather than partition-based ordering that limits concurrent clients to the number of partitions.

Push and pull delivery models control how messages flow from topic to subscriber. A push subscription causes Pub/Sub to deliver each message as an HTTP POST to a webhook endpoint such as Cloud Run without polling. Leased or pull-style delivery causes subscriber clients to obtain individual leased messages and hold each lease until processing succeeds. Choose push when the destination is an HTTP service that should be invoked directly for each message, with typical latencies on the order of 100 milliseconds. Pub/Sub also provides dead-letter queues and filtering to isolate unprocessable messages and select which messages reach a subscriber.

3.4Building the Cloud Run Event Receiver

A Cloud Run event receiver is an HTTP service that accepts CloudEvents from Eventarc or push requests from Pub/Sub. Data flows from the Pub/Sub topic to the subscription or trigger, then as an HTTP request to the Cloud Run service URL, where the service logs the event message and message data. The payload includes fields such as message data and message ID, and the CloudEvents request carries metadata such as ID, source, type, and time.

Trust boundaries control whether delivery can reach the receiver. All Cloud Run services are deployed privately by default and cannot be accessed without authentication, while --allow-unauthenticated deploys a publicly accessible receiver. To accept authenticated invocations, the trigger must use a service account with roles/run.invoker on the receiver service. Configuring routing from Pub/Sub to Cloud Run follows an ordered flow: first deploy the receiver service, then create the Eventarc trigger with --destination-run-service, --destination-run-region, and --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished", then select the transport topic by omitting --transport-topic to create a new topic or setting it to reuse an existing topic, then publish a message with gcloud pubsub topics publish to generate an event. Although the trigger is created immediately, it can take up to two minutes to become fully functional.

Versioning, exposing, and securing APIs is the practice of publishing backend services through a managed entry point while evolving them without breaking existing clients. On Google Cloud, Apigee (opens in a new tab) sits in front of backends such as Cloud Run to validate requests and enforce authentication. Traffic flows from the client caller to Apigee and then from Apigee to the backend service, so policy checks run before requests reach application code.

4.1Securing APIs with Apigee and Access Controls

Secure API endpoints with Apigee means placing policy checks between the client and the backend so unsafe traffic never reaches application code. Apigee enforces request validation that checks the shape and content of incoming requests, traffic control that limits volume and protects backends from overload, and authentication that verifies caller identity before granting access. Because these checks run centrally, individual backends do not reimplement the same logic and threat protection can be updated once for all versions.

Apigee provides gateway threat-protection policies that sanitize input at the gateway layer. The JSONThreatProtection policy blocks malformed or oversized JSON payloads, the XMLThreatProtection policy blocks malformed or oversized XML payloads, the RegularExpressionProtection policy blocks SQL, NoSQL, and command injection patterns, and the SOAPMessageValidation policy validates SOAP messages against expected structure. API keys are verified by Extensible Service Proxy V2 (ESPv2) with Service Control, and application restrictions bind a key to allowed websites, IP addresses, or apps so a request from an unlisted referrer or address is rejected even if the key is valid. For HTTP referrers the restriction must include a scheme, so https://example.com/* is valid while example.com/* is not.

4.2Exposing Backends with API Proxies and Products

An API proxy is the HTTP endpoint on Apigee that maps a public URL to a backend service and defines expected query parameters, headers, body, credentials, and response format. The proxy isolates the app developer from the backend, so the team can change a database, move hosts, or revise internal logic as long as the public API stays consistent. Policies run on Apigee, not on the backend, to add transformations, security checks, conditional logic, and custom code. Apigee also validates payload structure and enforces one-way and two-way Transport Layer Security (TLS) including mutual TLS at ingress, plus OAuth and JSON Web Token (JWT) verification.

An API product is a bundle of one or more proxies combined with a service plan that sets access limits, security, and monitoring. The product is the central mechanism for authorization, and multiple products can share the same proxy with different properties, such as one product with 1000 requests per day at a low price and another with a higher limit at a higher price. Publishing and consuming a product follows an ordered handoff. First, the provider creates proxies that map public URLs to backends. Then the provider creates a product that bundles the proxies with limits. Then the provider deploys the proxies and product. Then the developer registers a client app through automated Developer Services or manual approval. Then the developer receives an API key that must be included in every request. Then the developer calls the API through the proxies while Apigee authenticates the key. Revocation immediately stops access.

4.3Managing Traffic with SpikeArrest and Quota

Traffic management with SpikeArrest and Quota policies keeps app traffic within backend capacity and prevents one client from using more than permitted. Both policies can be used in one proxy when a service needs surge protection and contractual limits together. Apigee also provides caching, mediation, and analytics to reduce backend load and reveal usage patterns, including specialized LLMTokenQuota and PromptTokenLimit policies for generative AI token costs.

A quota value set on an API product does not automatically enforce itself; the value is a default limit referenced by Quota policies in the proxies, so updating the product setting updates what those policies enforce. An operation-level quota takes precedence over the product-level quota. The Quota policy is computationally expensive, so for high-traffic APIs it should use longer intervals such as a day or month.

Gateway options on Google Cloud differ by scope. API Gateway provides a centralized secure entry point for externally exposed APIs fronting serverless backends, Cloud Endpoints streamlines APIs on GKE and Cloud Run with key generation and OpenAPI automation, and Apigee provides enterprise-scale management with advanced threat protection (opens in a new tab), OAuth 2.0, caching, quotas, mediation, and deep analytics. For increased privacy, expose applications through Apigee or Apigee hybrid with end-to-end mutual TLS, optionally using a shared VPC with gated ingress (opens in a new tab) controls.

4.4Versioning APIs and Managing Lifecycle Changes

API versioning is the method for evolving an API without breaking existing clients. Additive changes preserve backward compatibility, including new optional parameters and new response properties that REST clients ignore if unknown. Breaking changes alter the existing contract and force clients to change, such as renaming functions, values, or properties or changing types like integer to string. When a stable endpoint needs a significant change, the change is placed in a new endpoint and bundled into a new API version rather than modifying the existing endpoint.

Stable, beta, and deprecated endpoint states communicate whether breaking changes are allowed and whether removal is planned. A stable endpoint is not expected to change, with no breaking changes except extreme cases such as security fixes. A beta endpoint is in active development and may change, so callers should track release notes. A deprecated endpoint is still supported and usable now but will be deleted in a future release, at which point code still using it will break. Unmarked endpoints in API Explorer and the 4.0 API Reference are considered stable.

Migrating to a new version moves client code from the old contract and address to the new contract in a controlled order. First, audit all scripts, integrations, and tools that invoke legacy hosts. Then set up OAuth 2.0 access, IAM permissions, and updated scopes. Then map endpoints and update base URLs to regional endpoints such as [api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/..., where the version can be v1alpha, v1beta, or v1. Then update request payloads and response handling for resource-oriented design and schema changes. Then validate changes in staging before production. Auditing is language-dependent because compiled languages surface mismatches as compile errors, while dynamic languages such as JavaScript, Ruby, and Python may need runtime unit tests with real API calls.

Key Facts

• Source code deployed to Cloud Run flows to Cloud Build for image creation, then to Artifact Registry for storage, and finally to Cloud Run as a revision that must listen on the port defined by the PORT environment variable.
• The deployer account needs Cloud Run Source Developer on the project, while the Compute Engine default service account used by Cloud Build needs Cloud Run Builder on the project.
• 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, event source filters cannot be modified after creation, and a new trigger can take up to two minutes to move from inactive to active.
• A private Cloud Run service requires the trigger service account to hold Cloud Run Invoker for authenticated Pub/Sub push delivery with OIDC tokens.