Cloud Run Functions and Events

The product name and the architecture changed more than once, so older articles disagree with each other. The timeline that matters:

Three things follow from the table. First, "Cloud Run functions" covers both functions created with the Cloud Functions v2 API (gcloud functions deploy) and functions deployed through the Cloud Run API (gcloud run deploy --function); both end up as a Cloud Run service. Second, 1st gen is still supported and can be created with gcloud functions deploy --no-gen2, but no new design should start there. Third, older guides still show the gcloud functions deploy flow with runtimes such as nodejs12, which has long been unsupported; the current approach is the runtime list in the official documentation.

A Cloud Run function is source code plus an entry point: the name of a function (or the fully qualified class name in Java). At build time Google Cloud buildpacks combine your source with the Functions Framework, an open source library for each language that starts an HTTP server, translates incoming requests into calls of your function and takes care of logging and error handling. The same library runs on your laptop, so what you test locally is what runs in the cloud. The framework exists for Java, Node.js, Python, Go, .NET, Ruby and PHP.

There are two function signatures:

In Java the two signatures are interfaces from the functions-framework-api artifact:

BackgroundFunction (a legacy, non-CloudEvents signature that predates the CloudEvents interface) still compiles, but new code should use CloudEventsFunction. The API artifact is provided-scope: the platform supplies the framework at run time, so it is not packaged in your application.

Reference: Write Cloud Run functions. Take the cloudevents.version and gson.version properties from the Maven Central pages of those artifacts, or from the official function samples, rather than copying values from an older guide.

A function (or any Cloud Run service) can be started in four ways. The choice is the main design decision for an event-driven component, so it deserves a table.

orders-api publishes an order-created message to the topic orders. The notifier function receives it, builds a confirmation email and sends it through SendGrid’s HTTPS API. The details of provider setup, domain authentication (SPF, DKIM, DMARC) and deliverability belong to Email sending; this section shows how the function is wired.

Design points that carry through the sections below:

When a user uploads a cover image to bookshelf-uploads-$PROJECT_ID, a function creates a thumbnail. The Cloud Storage event type is google.cloud.storage.object.v1.finalized, sent when an object has been created or overwritten. The data is the object’s metadata (bucket, name, contentType, size, generation), not the content: the function downloads the object with the Cloud Storage client library.

Prerequisites specific to Cloud Storage triggers: the Cloud Storage service agent (service-<project-number>@gs-project-accounts.iam.gserviceaccount.com) needs roles/pubsub.publisher on the project so that Cloud Storage can publish events; the trigger service account needs roles/eventarc.eventReceiver and roles/run.invoker; and the trigger location must match the bucket location. The function’s runtime service account needs roles/storage.objectUser on the bucket to read the original and write the thumbnail (or roles/storage.objectViewer plus roles/storage.objectCreator if you prefer to split them).

To avoid an infinite loop, write thumbnails to a different prefix and filter on it in the function, or better to a second bucket, because an Eventarc filter on Cloud Storage events selects by bucket and not by name prefix.

When you want to own the subscription, point it at the Cloud Run service URL. The subscription authenticates with an OIDC identity token minted for a service account; Cloud Run verifies the token and the roles/run.invoker binding before your code runs, so the function still needs no authentication code.

In the commands below notifier-http is an HTTP variant of the notifier deployed the same way with an HttpFunction. Because the delivery is a plain HTTP request rather than a CloudEvent, write the function as an HttpFunction (or a Spring @RestController) that parses the push envelope: {"message": {"data": "<base64>", "messageId": "…​", "attributes": {…​}}, "subscription": "…​"}. Respond with 204 (or any 2xx) to acknowledge; any other status, or a timeout, makes Pub/Sub redeliver according to the subscription’s retry policy.

HTTP functions are private by default: a request needs an identity token whose principal holds roles/run.invoker on the service. Making a function public means granting that role to the special principal allUsers (what --allow-unauthenticated does) and should be reserved for endpoints that are meant for the internet, ideally behind a load balancer with Cloud Armor (see Load balancing and Cloud Armor).

Reference: Authenticate invocations to Cloud Run and gcloud auth print-identity-token. The second form needs roles/iam.serviceAccountTokenCreator on the impersonated account.

Other callers: another Cloud Run service uses the metadata server to fetch an identity token with the target URL as audience (the client libraries do this); Cloud Scheduler and Workflows are configured with a service account and attach the token themselves; browsers and mobile apps authenticate users through Identity-Aware Proxy, Identity Platform or your own logic (see Identity and access). Functions created through the Cloud Functions API have also used the role roles/cloudfunctions.invoker; on a function deployed to Cloud Run the effective check is the Cloud Run invoker role on the service.

The inbound network can be restricted separately with ingress settings (--ingress internal, or internal-and-cloud-load-balancing), which complements IAM rather than replacing it.

Environment variables are visible to anyone who can read the revision, which is why a provider key belongs in Secret Manager. Secrets exposed as environment variables are resolved when an instance starts, so a new secret version is picked up by new instances only; mounted files can be refreshed without a restart when you reference latest. The Secret Manager roles, versions and rotation are on Secret Manager and Cloud KMS.

Cloud Run functions support Node.js, Python, Go, Java, Ruby, PHP and .NET. At the verification date the Java base images were java25, java21, java17 and java11, Node.js nodejs24 (with 22 and 20 still supported and 26 in preview), Python python314 and Go go127. Each runtime follows the language’s own lifecycle: Google deprecates a version around six months before it decommissions it, and a decommissioned runtime can no longer be deployed or, after the grace period, run. Java LTS releases are supported for years (the table lists the exact dates), while a version that the language community has retired is removed.

Two stacks provide the operating system for the base images, referred to as google-24 and google-22. A function can reference the image by short name (java25), by stack-qualified alias (google-24/java25) or by the full Artifact Registry path. By default a deployed function opts in to automatic base image updates: Google patches the operating system and runtime layers without a rebuild or a new revision of your code, which is a security benefit and the reason to avoid custom images unless you need them. Opting out is possible when you must control every change of the image; the linked page lists the flag and its effects.

Reference: Cloud Run functions runtimes. Because the tables change several times a year, plan a recurring check of the runtime support schedule for each function, ideally in the same dashboard that tracks other dependencies.

The Functions Framework runs the same HTTP server on your machine. For Java, add the Functions Framework Maven plugin and run the function in place:

Reference: Functions Framework and functions-framework-java. Use the Pub/Sub emulator (gcloud beta emulators pubsub start) when you need a real topic locally, and a mock HTTP server in place of the email provider.

Unit tests call the function class directly. For an HttpFunction, mock HttpRequest and HttpResponse and capture the writer; for a CloudEventsFunction, build a CloudEvent with CloudEventBuilder.v1() from the CloudEvents SDK. Keep the HTTP call behind a small interface so tests substitute it. This is the same approach as any Java unit testing; see Unit and integration testing for tools.

CI and deployment from GitHub Actions or GitLab should not use a downloaded service-account key. Use Workload Identity Federation, which exchanges the pipeline’s OIDC token for short-lived credentials (the setup is on Identity and access). A minimal GitHub Actions job:

Reference: Continuous deployment to Cloud Run and the google-github-actions/auth documentation. The deployer service account needs the roles listed in the IAM table above. Cloud Build can run the same pipeline when you prefer to stay inside Google Cloud; see Developer tools and DevOps.

The function and its trigger are two resources. In Terraform (provider hashicorp/google, version 8 at the verification date) a function deployed from a container image is a google_cloud_run_v2_service, and an Eventarc trigger is google_eventarc_trigger:

Reference: Eventarc triggers with Terraform and the provider documentation. Source-based deployment with buildpacks is a CLI feature; with Terraform you deploy an image built by a pipeline. The wider IaC picture is on Infrastructure as code.

The supported route is the gcloud functions upgrade command, generally available since 2026-08-10. It works in stages so that you can roll back until you commit:

Reference: Upgrade a 1st gen Cloud Run function to Cloud Run and gcloud functions upgrade. Things to check during the redirect step: the function URL changes (the new one is a run.app URL), event triggers become Eventarc triggers, Pub/Sub-triggered functions need idempotent handlers because both copies may briefly see events, legacy background-function signatures should move to CloudEventsFunction, and the runtime must be a supported version. 1st gen remains supported with no announced shutdown date, so the migration is a planned improvement (concurrency, longer timeouts, traffic splitting, 1,000 concurrent requests) rather than an emergency.

The comparison with other compute options is on Choosing a compute service. For the AWS analogue of this page, see Lambda: event-driven and serverless apps.

Cloud Run functions are billed as Cloud Run: you pay for the CPU, memory and requests an instance uses. Two billing modes exist. With request-based billing (the default for functions) you pay only while requests are being processed, plus a small per-request fee, and idle instances are free apart from reserved minimum instances; with instance-based billing you pay for the full instance lifetime and get CPU outside requests. Free monthly allowances for requests and compute time exist and are listed on the pricing page, together with the discounts for committed use. 1st gen functions have their own price list, based on invocations, compute time and networking. Costs outside the function matter as much as the function itself:

Cost levers: lower --max-instances to cap a burst, reduce memory and CPU to what the workload needs, avoid --min-instances unless latency requires it, batch events when the source allows it, and use budgets with alerts. Always read the current numbers on Cloud Run pricing and Eventarc pricing; this page deliberately states none, because they change and vary by region.

Cloud Run functions inherit the limits of Cloud Run. The ones that most often surface in event-driven designs:

Check the Cloud Run quotas and Eventarc quotas pages for the current values, and request increases from IAM & Admin, then Quotas & System Limits.

Read logs with gcloud run services logs read or in Cloud Run, then the service, then Logs. The Eventarc Triggers page shows the transport and delivery metrics, and Cloud Monitoring graphs request counts, latency and instance counts (see Monitoring and observability).

Delete in dependency order; the Eventarc trigger first, because it holds the transport subscription:

Reference: gcloud eventarc triggers delete. Deleting a secret removes all its versions at once and cannot be undone. Source deploys also leave images in the Artifact Registry repository cloud-run-source-deploy and sources in a Cloud Storage bucket created by the build; delete those, and any thumbnail objects in the uploads buckets (remember Cloud Storage soft delete can retain deleted objects for its retention period). The simplest cleanup for a learning project is to delete the whole throwaway project with gcloud projects delete "$PROJECT_ID", which schedules removal after a 30-day recovery window.