Nov 17, 202612 min read

Cloud Run Cold Starts: Min Instances, Startup CPU Boost and Faster Containers

What happens during a Google Cloud Run cold start, how min instances, startup CPU boost, the execution environment and startup probes change it, how image and dependency size matter, Go and Node.js code and Dockerfiles that start fast, and how Encore deployments relate to each lever.

Illustration for Cloud Run Cold Starts: Min Instances, Startup CPU Boost and Faster Containers

A Cloud Run cold start is the delay a request sees when no instance is free to serve it and Cloud Run has to start a new container first. It happens most often when a service scales up from zero, and also when traffic jumps faster than instances can be added. The fix is a mix of platform settings that keep or speed up instances and code that becomes ready to serve quickly.

Short answer: set service-level min instances to 1 or more so a warm instance is always ready, turn on startup CPU boost so new instances get extra CPU while they start, and make the container itself fast: listen on PORT before doing optional work, initialize clients lazily, and, for Node.js, bundle the code and start it with node. Measure the result with the container/startup_latencies metric.

This guide explains each lever, the settings in gcloud and Terraform, Go and Node.js code and Dockerfiles that start fast, and how Encore deployments fit in.

What happens during a Cloud Run cold start

Per the Cloud Run development tips, starting an instance has three steps:

  1. Downloading the container image, using image streaming so the container can start before the whole image arrives.
  2. Starting the container by running its entrypoint.
  3. Waiting for the container to listen on the configured port, which is what the default startup probe checks.

Requests that arrive while no instance is ready wait in a queue for up to 3.5 times the service's average startup time or 10 seconds, whichever is greater. Everything your process does before it opens the port, such as loading modules, connecting to databases or reading configuration, adds directly to that wait.

Cold start levers at a glance

LeverWhat it changesCost
Min instancesKeeps instances warm, so most requests never waitIdle instances billed at a lower rate with request-based billing
Startup CPU boostMore CPU during startup and for 10 seconds afterBoosted CPU billed during startup
First generation environmentFaster cold starts than second generation for some servicesLess CPU and network performance under sustained load
Startup probeTells Cloud Run when the instance is readyNone
Lean startup codeLess work before the port opensEngineering time
Fewer files at startupFewer remote file reads during bootBuild step for bundling

Min instances

Min instances keep a number of instances running even when they serve no requests, so a request arriving after a quiet period finds a warm instance. Google recommends setting it at the service level, which applies across revisions and takes effect without a new deployment, as the min instances docs describe:

~
# Service-level minimum, no new revision needed$ gcloud run services update api --region europe-west1 --min 1 # Check the current setting$ gcloud run services describe api --region europe-west1

Three details decide whether min instances are worth it:

  • Billing. With request-based billing, idle minimum instances are billed at a lower rate than active ones, and with a minimum of 0 there is no idle charge. With instance-based billing, every instance is billed at the default rate for its whole lifetime.
  • Best effort. The minimum is a target, not a guarantee. Capacity shortages, infrastructure rebalancing or a container that crashes at startup can drop you below it for a while, and Google suggests at least 3 for high availability.
  • Only one layer. A warm instance absorbs requests up to its concurrency limit. A burst beyond that still starts new instances, so startup speed still matters with min instances set.

Google advises against combining service-level and revision-level minimums, and revision-level minimums with traffic tags keep every tagged revision warm, which bills for revisions nobody uses.

Startup CPU boost

Startup CPU boost gives an instance extra CPU while it starts and for 10 seconds after it has started, according to the CPU configuration docs:

CPU limitBoosted CPU
Up to 12
24
48
6 or 88

You pay for the boosted CPU for that window, so a service with a 2 vCPU limit is billed for 4 vCPU during startup. It helps most where startup is CPU-bound, such as a Node.js app parsing many modules or a runtime with JIT warmup, and least for a small Go binary that is ready in milliseconds.

~
$ gcloud run services update api --region europe-west1 --cpu-boost# Turn it off again$ gcloud run services update api --region europe-west1 --no-cpu-boost

First or second generation execution environment

Cloud Run services can run on the first generation environment, based on gVisor, or the second generation, a microVM. The execution environment docs say the second generation performs better under sustained load but has longer cold starts than the first for some services. Google suggests first generation for bursty traffic that scales out fast, infrequent traffic that often scales from zero, and services under 512 MiB of memory, which second generation does not support.

The default is unspecified, which lets Cloud Run pick, and you can choose explicitly by deploying with --execution-environment gen1 or gen2. Second generation is required for features such as NFS mounts, so check what your service uses before switching.

Startup probes

When you configure nothing, Cloud Run adds a TCP startup probe on the container port with a 240 second timeout and period and a failure threshold of 1, per the health check docs. The instance is considered ready as soon as the port accepts a connection, and traffic can be routed to it immediately.

A server that opens its port before it can serve will receive requests it fails, and an HTTP startup probe on a health endpoint fixes that. A server that does all its initialization before opening the port is safe but slow, and every second of that work is cold start latency. The better design is to open the port early and move optional work out of the startup path.

Image size and dependencies

Cloud Run streams container images, so the size of the base image matters less than how many files the process reads while it boots. The Node.js tips explain that each file your code loads at startup is fetched from a remote location, and a typical node_modules tree means thousands of small reads. Bundling the app into a few files and lazy loading rarely used packages reduces that directly. For Go, the binary is one file, and a small, static image mostly saves pull and build time rather than cold start time.

Go: start fast on Cloud Run

Go services usually start quickly, and the remaining time is usually spent in init functions and in clients created before ListenAndServe. Keep main short, create rarely used clients on first use, and listen as soon as possible:

// main.go package main import ( "context" "log" "net/http" "os" "sync" "time" "cloud.google.com/go/storage" ) // Created on first use, not at startup. Only requests that need the // client pay for creating it. var storageClient = sync.OnceValues(func() (*storage.Client, error) { return storage.NewClient(context.Background()) }) func main() { port := os.Getenv("PORT") if port == "" { port = "8080" } mux := http.NewServeMux() mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusNoContent) }) mux.HandleFunc("GET /exports/{name}", func(w http.ResponseWriter, r *http.Request) { client, err := storageClient() if err != nil { http.Error(w, "storage unavailable", http.StatusServiceUnavailable) return } attrs, err := client.Bucket(os.Getenv("EXPORT_BUCKET")).Object(r.PathValue("name")).Attrs(r.Context()) if err != nil { http.Error(w, "not found", http.StatusNotFound) return } w.Header().Set("Content-Type", "text/plain") w.Write([]byte(attrs.Updated.Format(time.RFC3339))) }) // Listen as soon as possible: the startup probe passes once the port is open. log.Printf("listening on :%s", port) log.Fatal(http.ListenAndServe(":"+port, mux)) }

sync.OnceValues creates the client once, on the first request that needs it, and caches the result for every later request on that instance. Clients used by nearly every request, such as a database pool, are better created at startup, since the first request would wait for them anyway. The trade-off Google notes for lazy initialization is that the first request that needs the object pays its cost.

A static binary on a minimal base image keeps the image small:

# Dockerfile FROM golang:1.25 AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/server . FROM gcr.io/distroless/static-debian12:nonroot COPY --from=build /out/server /server ENTRYPOINT ["/server"]

The distroless static image includes CA certificates, which the Cloud Storage client needs for TLS. A scratch image does not, so copy them in if you use one.

Node.js: start fast on Cloud Run

In Node.js, most cold start time goes to loading modules, and Google's Node.js tips list three fixes: start with node rather than npm start, bundle the code, and lazy load dependencies with dynamic import(). The node --trace-event-categories node.module_timer command from the same page shows which modules take longest to load.

// src/server.ts import { createServer } from "node:http"; import type { Storage } from "@google-cloud/storage"; // Loaded on first use with a dynamic import, so startup does not read the // SDK's files. let storage: Promise<Storage> | undefined; function getStorage(): Promise<Storage> { storage ??= import("@google-cloud/storage").then(({ Storage }) => new Storage()); return storage; } const server = createServer(async (req, res) => { const url = new URL(req.url ?? "/", "http://localhost"); if (url.pathname === "/healthz") { res.writeHead(204).end(); return; } const match = url.pathname.match(/^\/exports\/([^/]+)$/); if (req.method === "GET" && match) { try { const gcs = await getStorage(); const [meta] = await gcs.bucket(process.env.EXPORT_BUCKET!).file(match[1]).getMetadata(); res.writeHead(200, { "content-type": "text/plain" }).end(String(meta.updated)); } catch { res.writeHead(404).end("not found"); } return; } res.writeHead(404).end(); }); server.listen(Number(process.env.PORT ?? 8080), () => { console.log(`listening on :${process.env.PORT ?? 8080}`); });

The import type line is erased at compile time, so the SDK is only loaded when getStorage first runs. Bundling with esbuild and code splitting puts the SDK in a separate chunk that is read on first use:

# Dockerfile FROM node:22-slim AS build WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npx esbuild src/server.ts --bundle --platform=node --target=node22 \ --format=esm --splitting --outdir=dist \ "--banner:js=import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);" FROM node:22-slim WORKDIR /app ENV NODE_ENV=production COPY --from=build /app/dist ./dist RUN echo '{"type":"module"}' > dist/package.json CMD ["node", "dist/server.js"]

The banner gives the ESM bundle a require function, which CommonJS dependencies such as the Google Cloud SDK call for Node built-ins. Without it, the lazily loaded chunk fails with Dynamic require of "stream" is not supported. The runtime image contains only the bundle, without node_modules, unless a dependency has native code or reads files from its package at runtime.

All the settings in gcloud and Terraform

A deploy that applies every lever from this guide:

~
$ gcloud run deploy api \ --image europe-west1-docker.pkg.dev/my-project/apps/api:v1 \ --region europe-west1 \ --min 1 \ --cpu 1 --memory 512Mi \ --cpu-boost \ --execution-environment gen1 \ --startup-probe httpGet.path=/healthz,periodSeconds=1,timeoutSeconds=1,failureThreshold=30

The same service in Terraform, using the service-level scaling block for min instances:

# cloud_run.tf resource "google_cloud_run_v2_service" "api" { name = "api" location = "europe-west1" # Service-level minimum: kept warm across revisions, changed without a deploy. scaling { min_instance_count = 1 } template { execution_environment = "EXECUTION_ENVIRONMENT_GEN1" max_instance_request_concurrency = 80 containers { image = "europe-west1-docker.pkg.dev/my-project/apps/api:v1" resources { limits = { cpu = "1" memory = "512Mi" } cpu_idle = true # request-based billing startup_cpu_boost = true } startup_probe { http_get { path = "/healthz" } period_seconds = 1 timeout_seconds = 1 failure_threshold = 30 } } } }

The probe checks every second for up to 30 seconds, so a ready instance gets traffic within a second of becoming healthy. For the rest of a Cloud Run setup in Terraform, including IAM and public access, see the Cloud Run Terraform guide.

Measure cold starts

The Cloud Monitoring metric run.googleapis.com/container/startup_latencies records how long new instances take to start. Compare it before and after each change, and look at request latency percentiles alongside it: a service with min instances can still show slow p99 requests during bursts, which points at startup time rather than the minimum.

How Encore deploys to Cloud Run

Encore

Encore gives you infrastructure from code on your own GCP project: you declare services, databases, buckets and Pub/Sub topics in the application, and Encore provisions them and deploys the services to Cloud Run or GKE. The GCP infrastructure docs describe what Encore configures on Cloud Run: health check grace periods so containers have time to start, zero-downtime deployments behind a load balancer, secrets injected as environment variables, and Encore provisions a service account for the service. They do not list min instances or startup CPU boost, so do not count on Encore setting either for you.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create reports --example=hello-world$ cd reports && mkdir exports
// exports/exports.go package exports import ( "context" "errors" "encore.dev/beta/errs" "encore.dev/storage/objects" ) // Declared in code; Encore provisions a Cloud Storage bucket on GCP. var Exports = objects.NewBucket("exports", objects.BucketConfig{}) type ExportInfo struct { Name string `json:"name"` Size int64 `json:"size"` ContentType string `json:"content_type"` } //encore:api public method=GET path=/exports/:name func Get(ctx context.Context, name string) (*ExportInfo, error) { attrs, err := Exports.Attrs(ctx, name) if errors.Is(err, objects.ErrObjectNotFound) { return nil, &errs.Error{Code: errs.NotFound, Message: "export not found"} } else if err != nil { return nil, err } return &ExportInfo{Name: attrs.Name, Size: attrs.Size, ContentType: attrs.ContentType}, nil }

This is the same endpoint as the hand-written Go server, without the client setup, the port handling or the Dockerfile. The bucket is declared as a resource, as the object storage docs explain, and Encore provisions a service account for the service and grants it access to the bucket. The app compiles into a Go binary, and encore build docker, which follows the same code path as Encore's own CI, packages Go apps on a scratch base image by default, per the Docker build docs.

What Encore does not remove is the trade-off of scaling to zero. Two options exist for a service whose users notice cold starts:

  • Deploy the environment to GKE. Encore's GCP docs describe a GKE option in which each service runs as a Kubernetes Deployment, so pods keep running between requests instead of scaling from zero.
  • Self-host the image on Cloud Run. Build it with encore build docker, passing an infrastructure config file for the bucket, push it to Artifact Registry and deploy it with the gcloud run deploy flags above, including --min and --cpu-boost. You then own the Cloud Run settings and the bucket, and the CLI reference lists the build flags, such as --base and --arch.

For an AI coding agent, the useful split is that application code stays the same across all three paths, so it can add an endpoint or a bucket without knowing whether the service will run warm on GKE or scale from zero on Cloud Run.

Best fit: teams on GCP that want services and their infrastructure declared in code, and that decide per environment whether cold starts are acceptable.

Frequently asked questions

How do I reduce Cloud Run cold starts?

Keep at least one instance warm with gcloud run services update SERVICE --min 1, enable startup CPU boost with --cpu-boost, and make the container start fast: listen on the port before doing optional work, initialize rarely used clients lazily, keep dependencies small and, for Node.js, bundle the code and start it with node instead of npm. Services with bursty or infrequent traffic can also use the first generation execution environment, which Google describes as having faster cold starts.

Do Cloud Run min instances cost money when idle?

Idle minimum instances cost money, at a lower rate: with request-based billing, idle minimum instances are billed at a lower rate than active ones, and with min instances set to 0 you are not billed for idle instances at all. With instance-based billing you pay the default rate for the whole instance lifetime, idle or not.

What does Cloud Run startup CPU boost do?

It gives an instance extra CPU while it starts and for 10 seconds afterwards: 2 vCPU for a limit up to 1, 4 for 2, and 8 for 4 or more. You pay for the boosted CPU during that time. Enable it with gcloud run services update SERVICE --cpu-boost or startup_cpu_boost in Terraform.

Does container image size affect Cloud Run cold starts?

Less than you might expect, since Cloud Run streams the image rather than downloading it all before starting. What matters more is what the process reads and runs at startup: every file a Node.js app loads at boot is fetched remotely, so bundling and lazy loading help more than shaving base image megabytes.

Does Encore configure Cloud Run min instances?

Encore's GCP documentation does not list min instances or startup CPU boost among the Cloud Run settings it manages, so do not assume Encore sets them. Encore configures health check grace periods and a load balancer, and provisions a service account for the service. For services that cannot tolerate cold starts, Encore can deploy to GKE instead, or you can build the image with encore build docker and deploy it to Cloud Run with your own flags.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders