Cloud Run container lifecycle

Exam guide§2.1

A Cloud Run service is the resource you interact with - deploy a new image, roll back to a revision, or change config (env vars, scaling). Each deploy creates an immutable revision; the first deploy creates the service and its first revision. Every service gets a unique, permanent HTTPS endpoint on a run.app subdomain that never changes. To serve a request, Cloud Run starts a container and forwards the request to it.

Deploys, revisions, and traffic splitting are covered on Revisions & traffic splitting. This page is about what happens to a container instance at runtime.

The five states

The five container states and the transitions between them: a container starts, serves requests, goes idle, and is eventually stopped - gracefully via SIGTERM or forcefully on a crash or memory-limit breach.

• Starting - Cloud Run materializes the image and starts your app.
• Serving requests - the container is handling web requests.
• Idle - the container is not handling requests (CPU throttled, no charge).
• Shutting down - if you handle the shutdown hook, you get to stop gracefully.
• Stopped - the container is gone.

Starting

Starting a container is four steps: materialize the image, run the app, wait for it to accept TCP connections, then forward requests to the serving container.

The Starting phase begins when Cloud Run pulls the image and ends when the container starts serving. Four steps:

1. Cloud Run creates the root filesystem by materializing the container image.
2. It runs the container's entrypoint (your application).
3. It probes port 8080 (configurable) to check whether the app is ready.
4. Once the app accepts TCP connections, Cloud Run forwards requests to it.

⚠GotchaOnly open the port when you are ready

Cloud Run treats "accepts TCP connections" as "ready for traffic." If your app opens the port before it can actually serve, requests hit it too early. Open the port only when you are ready to handle requests - or configure an explicit startup probe.

#NumbersHealth checks

• Startup and liveness probes support HTTP, TCP, and gRPC, configured via YAML for new and existing services.
• A startup probe determines when a container has started and is ready to accept traffic.
• Default probe target is port 8080.

Where the image comes from

Two pulls, two sources: deploying copies the image from Artifact Registry into Cloud Run internal storage; every container start then pulls from that internal copy.

Cloud Run pulls a container image at two distinct moments, from two sources:

• Deploy (first time): Cloud Run pulls and copies the image from Artifact Registry into its own internal storage.
• Start (every new container): Cloud Run pulls the image from internal storage, not Artifact Registry.

⚠GotchaInternal copy insulates you from Artifact Registry

Because Cloud Run keeps its own copy, container starts do not depend on Artifact Registry - your service survives an Artifact Registry outage, or even accidentally deleting the deployed image from Artifact Registry. Internal storage is also optimized so large images load as fast as tiny ones.

Idle

A container stays in Serving requests as long as it handles web requests. After 100 ms with no requests it transitions to Idle. An idle container:

• Does not serve requests and does not incur charges.
• Has its CPU throttled to nearly zero - your app runs very slowly.
• Can be shut down at any time (you get a shutdown hook to clean up).

Going Idle → Serving is seamless: on the next request Cloud Run unthrottles the CPU and returns full access immediately, so users see no lag.

⚠GotchaThrottled CPU breaks background work

With CPU throttled to ~zero, you can't reliably run background tasks, and network requests to third parties are likely to fail while idle. Options: set CPU always allocated (charged for the container's whole lifecycle, useful for short-lived background/async work), or schedule work with Cloud Tasks.

#NumbersIdle facts

• Idle transition after 100 ms with no requests.
• Cloud Run may keep instances idle for up to 15 minutes to absorb traffic spikes and cut cold starts.
• Set minimum instances to always keep some instances ready to serve.

Shutting down

If a container is idle, Cloud Run can decide to stop it. By default a container just disappears when shut down. To stop gracefully, build your app to handle the SIGTERM signal - it warns the app that shutdown is imminent and gives it 10 seconds to clean up before removal.

Graceful shutdown work worth doing in those 10 seconds:

1. Close open TCP connections, file descriptors, and database connections (downstream systems are slow to time out idle connections - under heavy scaling you can hit max-connection errors).
2. Flush any buffers of batched data (telemetry, etc.).
3. Write a log entry to help debugging later.

Most languages provide libraries to trap termination signals like SIGTERM and run routines before exit.

Stopped

A container reaches Stopped two ways:

• Graceful - it handled SIGTERM, cleaned up within 10 s, then exited.
• Forceful - it did not handle SIGTERM (Cloud Run stops it immediately, process just disappears), or it stopped suddenly.

Cloud Run never stops a container while it serves requests under normal circumstances. But a container can stop suddenly if:

• Your application exits (e.g. a bug in your code), or
• It exceeds the memory limit (default 512 MiB per instance).

⚠GotchaA sudden stop fails in-flight requests

If a container stops while handling requests, all in-flight requests are terminated and fail with an error. While Cloud Run starts a replacement, new requests may have to wait.

#NumbersMemory limits

• Default memory per container instance (service revision or job): 512 MiB.
• Configurable up to 32 GiB.

Recap

#NumbersLifecycle numbers to remember

• Idle after: 100 ms with no requests.
• Kept idle: up to 15 minutes (cold-start buffer).
• SIGTERM grace period: 10 seconds.
• Default memory: 512 MiB (max 32 GiB).
• Startup probe port: 8080 (default).

?DECISIONWhy won't my container behave the way I expect?

Background/async work stalls when no traffic→Idle CPU throttle - set CPU always allocated or use Cloud Tasks

In-flight requests fail on redeploy/scale-down→Handle SIGTERM for graceful shutdown (10 s)

Container killed unexpectedly under load→Memory limit (512 MiB) - raise it, up to 32 GiB

First request after quiet period is slow→Cold start - set minimum instances

Requests hit the app before it's ready→Open the port / signal readiness only when ready; use a startup probe

Pick this when: match the symptom to the lifecycle cause