Cloud Run is Google Cloud’s fully managed platform for running containers without managing servers.

A container is a sealed box that holds your program together with everything it needs to run: the language runtime, libraries, and settings. Because the box carries its own supplies, it behaves the same on a laptop, in a test environment, and in production. Cloud Run takes that box, runs it on Google’s infrastructure, gives it a web address, and scales the number of running copies up and down automatically.

Before platforms like this, a team that wanted to run a web service had to rent virtual machines, install an operating system, patch it, set up a load balancer, configure autoscaling rules, and watch for failures. Each of those jobs is real work that has nothing to do with the product being built. Cloud Run exists to remove that work. You supply the container, and the platform handles servers, operating system patching, capacity planning, load balancing, certificates, and scaling.

Why advanced engineers care

Cloud Run is not a toy for small websites. It runs request-driven APIs, background batch work, event consumers, AI inference with GPUs, and internal tools at large scale. Its design choice is simple but powerful: it accepts standard containers and standard web traffic, so there is no proprietary framework to learn and moving away is relatively painless. That portability, combined with scale-to-zero economics, is why it has become a default landing zone for new workloads on Google Cloud.

The three families of Cloud Run workloads

Cloud Run offers distinct resource types for distinct jobs. Services respond to incoming requests such as web calls and webhooks. Jobs run a task to completion and then stop, which suits data processing and scheduled work. Worker pools, a newer addition, keep long-running background consumers alive without an HTTP front door. Understanding which one fits your workload is the first design decision you make, and it prevents many expensive mistakes later.

Every Cloud Run conversation uses the same small vocabulary, so learn each word properly once.

New terms are the biggest barrier when learning any platform. Below, every concept is defined by what it is, why it exists, and where you meet it. Read the cards slowly, because later chapters build on them without re-explaining.

Why immutability matters

Revisions can never be edited after creation. If you want a different memory size or a new environment variable, you create a new revision. This sounds restrictive, but it gives you something valuable: a permanent, auditable record of exactly what ran at any time, and a guaranteed way to roll back by pointing traffic at an older revision that is known to work.

Cloud Run feels simple on the surface because a lot of machinery is hidden beneath it.

At a high level, Cloud Run has a control plane and a data plane. The control plane is the part that accepts your deployment commands, stores your configuration, creates revisions, and decides how many instances should exist. The data plane is the part that actually receives user requests and runs your containers. Separating these two means that a busy moment in request traffic does not slow down deployments, and an ongoing deployment does not disturb live traffic.

flowchart TD
  U["User or Client"] --> GFE["Google Front End and Load Balancing"]
  GFE --> RT["Cloud Run Request Router"]
  RT --> I1["Instance A"]
  RT --> I2["Instance B"]
  RT --> I3["Instance C"]
  CP["Control Plane: Revisions, Autoscaler, Config"] -.-> RT
  CP -.-> I1
  CP -.-> I2
  CP -.-> I3
  I1 --> SVC["Other Google Cloud Services"]
  I2 --> SVC
  I3 --> SVC
        

Requests first reach Google’s global front end infrastructure, which terminates encrypted connections and applies protections. From there a router picks a ready instance of the correct revision. If none has spare capacity, the autoscaler is told to start another. The autoscaler is therefore part of the control plane, but its decisions are driven by signals coming from the data plane.

Execution environments

Each instance runs inside a sandbox so that one customer’s code cannot affect another’s. Cloud Run offers two execution environments. The first generation uses a lightweight sandbox that starts very quickly and is cost-efficient. The second generation provides a fuller Linux environment with broader system call compatibility, better network throughput in many cases, and support for features such as network file system mounts. If your application needs behavior that the lighter sandbox does not fully emulate, the second generation is the safer choice. If you want the fastest cold starts and your application is simple, the first generation can be attractive. Newer features increasingly assume the second generation, so check your requirements before choosing.

Supporting components

Following a single request from the browser to your code reveals most of Cloud Run’s behavior.

When someone calls your service URL, the request travels through several hands before your code sees it. Understanding each hand helps you diagnose delays, because a slow response might be slow at any of these stages and the fix differs for each.

sequenceDiagram
  participant C as Client
  participant G as Google Front End
  participant R as Router
  participant A as Autoscaler
  participant I as Instance
  C->>G: HTTPS request
  G->>R: Authenticated, forwarded request
  R->>R: Check IAM invoker permission
  alt Instance has free capacity
    R->>I: Deliver request
  else No free capacity
    R->>A: Signal need for new instance
    A->>I: Start container
    I-->>R: Startup check passed
    R->>I: Deliver queued request
  end
  I-->>C: Response
        

The instance lifecycle

An instance moves through stages: it is created, it starts and passes its startup check, it serves requests, it becomes idle when no requests are active, and eventually it is shut down. Before shutdown, Cloud Run sends a termination signal so your application can finish work and release resources. Treat that signal seriously, because applications that ignore it lose in-flight work or leave connections hanging.

Scaling is the heart of Cloud Run, and three settings decide almost everything.

Cloud Run scales the number of instances based mainly on incoming request pressure and CPU utilization. Unlike older platforms where you wrote scaling rules by hand, here the platform watches how many requests are in flight, compares that to each instance’s concurrency limit, and decides how many instances are needed. Your job is to set the boundaries and make your container healthy under them.

Concurrency: the most misunderstood setting

Concurrency is the number of simultaneous requests one instance may handle. A high value lets one instance serve many callers, which lowers cost and reduces how often new instances must start. A low value, even one, makes each request get a dedicated instance, which isolates requests from each other but multiplies instance count and cold starts. The right number depends on how your application behaves. Programs that mostly wait on databases and other services handle high concurrency well. Programs that burn CPU on each request, or that keep large per-request state in memory, need lower concurrency or they will slow down and run out of memory.

Minimum and maximum instances

Minimum instances keep a set number of copies warm even when traffic is zero, which removes cold starts for the first requests at the price of paying for those idle copies at a reduced rate. Maximum instances cap how far the service can scale, which protects downstream systems like databases from being overwhelmed and protects your budget from runaway traffic or attacks. A sensible production service sets both on purpose, rather than accepting defaults.

Understanding cold starts

A cold start is the delay when a request arrives and no ready instance exists. The platform must fetch the image, start the sandbox, launch your process, and wait for your application to report that it is ready. The time spent inside your own application, such as loading frameworks and warming connections, is usually the largest and most controllable part.

Cloud Run bills for what you use, but “what you use” depends on one key choice.

Every instance is configured with an amount of CPU and memory. You pick these per revision, from small fractions of a CPU up to several full CPUs, with generous memory ceilings for heavier workloads. Choosing the right size is a balancing act: too small and requests time out or the container is killed for exceeding memory, too large and you pay for capacity you never touch.

Two billing modes

The first mode is request-based billing. Here the CPU is available only while the instance is handling at least one request, and you are billed for the time requests are active, rounded up in small increments, plus a small charge per request count. Outside request handling, the CPU is throttled and effectively paused. This is ideal for typical web APIs because idle time costs nothing.

The second mode is instance-based billing, sometimes called always-on CPU. The CPU is fully available for the entire life of the instance, even between requests, and you are billed for the whole time the instance exists, without a per-request fee. This suits workloads that do background work after responding, keep websocket-style long connections busy, or run in-memory caches that need steady processing.

Hidden cost drivers

Compute is rarely the only line on the invoice. Network egress to the internet or across regions, calls to paid downstream services, logging volume, and build minutes all add up. A chatty service that logs every request body can spend more on logging than on compute. Cost discipline means looking at the entire bill, not only the Cloud Run line.

Committed use and free allowances

Google Cloud provides a monthly free allowance for Cloud Run usage and offers discounts for steady, predictable usage through committed use arrangements. Both are useful, but they should follow a measured baseline of real usage rather than guesses. Always confirm current pricing and allowances on the official pricing page, since amounts change over time.

Cloud Run asks your container to follow a few simple rules, and breaking them causes confusing failures.

The contract is short. Your container must listen for HTTP requests on the port the platform provides through an environment variable, and it must start listening within the startup window. It should be stateless, meaning it does not rely on local files or memory surviving between requests, because the next request may land on a different instance. It should write logs to standard output and standard error, and it should handle the termination signal calmly.

Startup, liveness and readiness thinking

Cloud Run supports startup probes and liveness probes. A startup probe tells the platform when your application has finished initializing and can start receiving traffic. Without a well-designed startup check, the platform may consider the container ready as soon as the port opens, even though your application is still loading data. A liveness probe periodically asks whether a running instance is still healthy; if it keeps failing, the instance is restarted. These probes turn vague “it sometimes hangs” problems into predictable, self-healing behavior.

Graceful shutdown in practice

Instances are shut down during scale-in, during new deployments, and during maintenance. The platform gives a short grace period after the termination signal. A well-behaved application stops accepting new work, finishes in-flight requests, flushes buffered logs and metrics, and closes database connections. An application that ignores the signal may be forcefully stopped, which shows up as dropped requests during every deployment.

Because revisions are immutable, Cloud Run gives you powerful, low-risk release tools for free.

Every deployment creates a new revision. By default, the newest revision receives all traffic, but you can change that. Cloud Run lets you split traffic by percentage between revisions, give a revision a named tag with its own test URL, and roll back instantly by moving traffic to an older revision. No servers are rebuilt and no load balancers are reconfigured; the router simply changes its weights.

flowchart LR
  D["Deploy new revision with no traffic"] --> T["Test via tagged URL"]
  T --> C1["Send 5 percent of traffic"]
  C1 --> M{"Metrics healthy?"}
  M -- Yes --> C2["Raise to 50 percent"]
  C2 --> F["Send 100 percent"]
  M -- No --> RB["Roll back to previous revision"]
        

Release strategies compared

Why a tagged URL is a hidden gem

A tag gives a revision a separate address that receives only deliberate test traffic. Teams use it to run smoke tests in a production-like environment before any customer sees the change. This closes the gap between a staging environment and reality, because the revision uses the real configuration, identity, and network paths.

Database changes and compatibility

During a rollout, two revisions run at the same time. That means every database change must be compatible with both the old and new code. The safe pattern is to add new structures first, deploy code that can use both, migrate, and only then remove the old structures. Ignoring this is a common reason canary releases fail even when the code is correct.

Networking decides who can reach your service and what your service can reach.

Cloud Run networking has two directions. Ingress is traffic coming in. Egress is traffic going out. Each direction has its own controls, and a secure design configures both deliberately.

Ingress controls

A service can accept traffic from anywhere on the internet, only from internal sources such as your private networks and other Google Cloud services, or only from internal sources plus a Google Cloud load balancer. The last option is the common choice for public production systems that need extra protection, because it forces every external request to pass through the load balancer where you can attach security policies and caching.

Egress and private networks

By default a service reaches the internet and public Google APIs directly. To talk to private resources, such as a database that has no public address, the service needs a path into a Virtual Private Cloud network. Two mechanisms exist. Direct VPC egress places the instance’s network interface directly into your subnet, which is simpler and generally faster. A Serverless VPC Access connector is an older approach that routes traffic through a small fleet of connector machines. Most new designs prefer the direct option. You can also choose whether all outbound traffic goes through the private network or only traffic destined for private addresses, which affects cost and how you control outbound internet access.

flowchart LR
  Internet["Internet Users"] --> LB["Global External Load Balancer"]
  LB --> ARM["Cloud Armor Policy"]
  ARM --> NEG["Serverless NEG"]
  NEG --> CR["Cloud Run Service"]
  CR --> VPC["VPC Subnet via Direct Egress"]
  VPC --> DB["Private Database"]
  VPC --> NAT["Cloud NAT"]
  NAT --> EXT["Approved External APIs"]
        

Why put a load balancer in front

Cloud Run security is about three questions: who may call you, who are you, and what do you trust.

Who may call you

Access to invoke a service is controlled by IAM through the invoker role. A service can be public, meaning anyone may call it, or private, meaning callers must present a valid identity token from an account that holds the invoker permission. Private by default is the healthier posture. Make a service public only when it truly serves anonymous users, and even then consider placing a load balancer and a firewall in front.

Who are you: the service identity

Every revision runs as a service account. This identity is what your code uses when it calls other Google Cloud services. The most common security failure is using the broad default account, which often carries wide permissions. The correct approach is to create a dedicated service account per service and grant it only the specific permissions it needs. If the service is compromised, the damage is limited to those few permissions.

Service-to-service calls

When one Cloud Run service calls another private one, the caller obtains an identity token for the target and sends it with the request. The platform checks the token and the invoker permission. This means internal microservices can be locked down without managing shared secrets or network allow lists.

Secrets and configuration

Passwords, API keys, and certificates belong in Secret Manager, not in the container image or plain environment variable files. Cloud Run can expose a secret to the container as an environment value or as a mounted file, and it can pin to a specific secret version or follow the latest. Pinning gives repeatability; following latest gives easier rotation. Access to each secret is granted to the service account individually.

Protecting the software supply chain

Cloud Run instances forget everything, so durable data must live elsewhere.

Because instances appear and vanish, anything written to the instance’s local disk is temporary. In fact, local disk space is an in-memory file system, so writing large temporary files consumes the memory you allocated. The design rule is simple: keep the container stateless, and place state in a service built for it.

Choosing a data home

The connection-count problem

A subtle trap appears when many instances each open several database connections. Fifty instances with ten connections each can exhaust a modest database. Solve this by capping maximum instances, keeping per-instance connection pools small, reusing connections across requests, and using a connection pooler or the managed connection features of the database service where available. Cloud Run can connect to Cloud SQL through a built-in secure path, so you do not need to open the database to the public internet.

Mounting storage as volumes

Cloud Run can mount Cloud Storage buckets as folders and can attach network file shares so that code expecting a normal file path keeps working. It can also provide a memory-backed volume for scratch space shared between containers in the same instance. These mounts are convenient for machine learning model files, shared assets, and legacy applications. They are not a replacement for a database, because object storage has different latency and consistency traits than a local disk.

Cloud Run is not only for web pages; it is an excellent reaction engine for events.

An event is a statement that something happened: a file arrived, a message was published, a record changed. Event-driven designs let services react without being tightly coupled, which makes systems easier to extend and more resilient to partial failures. Cloud Run fits naturally because it can wake from zero when an event arrives, do its job, and sleep again.

flowchart LR
  S["Storage Upload"] --> E["Eventarc"]
  P["Pub/Sub Topic"] --> R1["Cloud Run Service"]
  E --> R1
  SCH["Cloud Scheduler"] --> J["Cloud Run Job"]
  Q["Cloud Tasks Queue"] --> R2["Cloud Run Worker Service"]
  R1 --> Q
  R1 --> BQ["BigQuery"]
  R2 --> DB["Database"]
        

The main delivery tools

Designing for at-least-once delivery

Most messaging systems promise that a message will be delivered at least once, which means duplicates can happen. Your handler must be idempotent, meaning that processing the same message twice has the same final effect as processing it once. Common techniques include storing a unique message identifier and skipping repeats, or writing records using operations that naturally overwrite rather than add.

Acknowledgement and timeouts

For push-style delivery, the HTTP response is the acknowledgement. A success response says the message is handled; an error response asks for a retry. If your processing takes longer than the sender’s acknowledgement deadline, the message may be redelivered while you are still working on it. Keep handlers short, or accept the message quickly and hand long work to a job or a queue.

Not all work answers a request; some work simply has to be finished.

A Cloud Run job runs a container until it completes, then stops. There is no web address and no request handling. Jobs suit tasks like nightly report generation, data migration, image batch processing, and machine learning preparation. Each execution of a job can be split into many tasks that run at the same time, and each task learns its own index so it can pick its slice of the work.

How a job execution behaves

Designing parallel tasks well

The key skill is partitioning. If you must process one million files, you can divide them so that each of one hundred tasks handles ten thousand, selected by task index. This is far faster than a single long process and costs about the same, because you pay for total compute time rather than elapsed time. Plan for uneven slices, because tasks that finish early cannot help tasks that are still running unless you design a shared work queue.

Worker pools for continuous background consumers

Some workloads need to run all the time without receiving web requests, for example a consumer that pulls messages from a queue or a stream. Worker pools are designed for this: they keep a configured amount of capacity running and do not require your code to expose an HTTP endpoint. They are an alternative to forcing a background consumer into a service that must pretend to answer web calls.

You cannot log into an instance, so what your service reports about itself is everything you have.

Observability is the ability to understand what a system is doing from the outside. On Cloud Run, three signals matter: logs, metrics, and traces. Together they answer what happened, how much and how fast, and where time was spent.

Logs

Anything your container prints to standard output or standard error is collected automatically into Cloud Logging, along with request logs written by the platform. The best practice is structured logging, where each log entry is a small structured record with fields such as severity, message, and a request identifier, rather than a free-form sentence. Structured logs can be filtered and counted precisely, and the platform can link them to the request that produced them and to the trace.

Metrics

Cloud Run publishes built-in metrics without any setup. The important ones describe the shape of your service’s health.

Traces

A trace follows one request across several services, with each step timed. Cloud Run forwards tracing headers, so if your code propagates them to downstream calls, Cloud Trace can draw the full picture. Traces are the fastest way to discover that a slow API is actually waiting on one slow database query three services away.

Service level objectives

Instead of staring at raw graphs, define a promise: for example, that ninety-nine percent of requests succeed over a rolling month, or that ninety-five percent finish within a chosen time. Cloud Monitoring can track these objectives and alert when the error budget is being spent too fast. This turns vague unease into clear, agreed thresholds.

Experienced teams repeat a handful of patterns, and avoid a handful of traps.

Patterns that work well

Anti-patterns to avoid

Choosing a compute platform is about matching control, effort, and workload shape.

Google Cloud offers several ways to run code. No option is universally best. The right choice depends on how much control you need, how much operational work your team can carry, and how your traffic behaves.

When Cloud Run is the natural choice

Choose Cloud Run when your workload is stateless or keeps its state elsewhere, speaks HTTP or gRPC, tolerates instances coming and going, and benefits from scaling to zero. It is also an excellent default when the team is small and wants to spend time on product features instead of cluster care.

When to look elsewhere

Choose a cluster platform when you need fine control over scheduling, custom operators, privileged workloads, or tightly coupled stateful systems. Choose virtual machines when you need a specific operating system, kernel behavior, or hardware arrangement. Many mature organizations use several of these together, placing each workload on the platform whose strengths it needs.

A short checklist of habits separates smooth Cloud Run operations from noisy ones.

Best practices

Common mistakes

Seeing how the pieces combine in realistic situations makes the concepts stick.

Production readiness means planning for the day something breaks.

A Cloud Run service is a regional resource. Within a region, Google runs your instances across multiple zones, so the loss of a single zone does not normally take your service down. But a whole-region problem, a bad deployment, or a failing downstream dependency can still hurt. Resilience planning addresses each of these separately.

Going multi-region

To survive a regional outage and to serve users from nearby locations, deploy the same service to two or more regions and place a global external load balancer in front. The load balancer sends each user to the closest healthy region and shifts traffic away if a region stops responding. The cost of this design is extra complexity: data must be available in each region, deployments must be coordinated, and you must decide what happens to writes when regions disagree.

Protecting against bad releases

Most outages are caused by changes, not hardware. Canary rollouts, tagged test URLs, and rapid rollback by traffic shifting are your strongest defenses. Pair them with automated checks that compare error rate and latency of the new revision against the old one, and stop the rollout automatically when the numbers worsen.

Taming dependencies

Your service is only as reliable as the systems it calls. Set timeouts on every outbound call, retry carefully with growing delays and a limit, and use circuit breakers so that a failing dependency is skipped quickly instead of tying up all your concurrency slots. When a non-essential dependency fails, degrade gracefully by returning partial results rather than an error.

Quotas and limits

Projects have quotas on things such as the number of instances, CPU and memory in use per region, and request rates. Quotas protect everyone, but they can also surprise a fast-growing service. Review them before launches, request increases early, and set alerts on quota usage. Also remember that resource limits per instance and the maximum request duration are fixed ceilings you design around, so always confirm current values in the official documentation.

Short answers to the questions engineers ask most when adopting Cloud Run.

Yes. When a service has no traffic and no minimum instances, it can drop to zero instances and cost nothing for compute. The first request after that waits for a new instance to start, which is the cold start. Its length depends mostly on image size and your application’s startup work.

Yes, within the request timeout limit, which can be raised up to about an hour. Long-lived connections count as active requests, so they hold concurrency slots and affect scaling. Clients should be ready to reconnect when a connection ends.

Cloud Run functions let you deploy just a function and the platform builds the container for you, which is quick for small event handlers. Cloud Run itself accepts any container, so you control the runtime, the dependencies, and the full application structure.

Generally no. Instances are temporary and local storage does not persist. Run the application on Cloud Run and keep data in a managed database or storage service.

Set a maximum instance count, put a load balancer with a web application firewall and rate limits in front, keep the service private where possible, and add budget alerts. Together these bound both traffic and spending.

In request-based billing, the CPU is throttled once no requests are active, so work that continues after the response may stall. Finish the work before responding, switch to instance-based CPU allocation, or send the work to a queue or job.

Yes. Set the callee to accept internal traffic, give the caller’s service account the invoker permission on the callee, and have the caller attach an identity token. No public exposure or shared passwords are required.

Shift traffic back to the previous known-good revision. Because revisions are immutable and remain stored, the rollback takes effect within moments and does not require rebuilding anything.

Split when parts of the system have different scaling needs, permissions, or release schedules. Keep things together when splitting would only add network calls and operational overhead without a clear benefit.

Load test it and tune concurrency, CPU, and memory together while watching latency and instance count. This one exercise usually improves both performance and cost more than any other change.

Cloud Run gives you a simple promise with deep machinery behind it: bring a container, and Google runs it, scales it, secures its edge, and bills you for what you use. Mastering it means understanding the few ideas that drive everything else. Revisions give you safe releases. Concurrency and instance limits shape cost and stability. Request-based and instance-based CPU decide how your background work behaves. Identity and ingress settings decide who can reach you and what you can reach. Statelessness, idempotency, and good observability keep the system calm when things go wrong.

Used with discipline, Cloud Run lets a small team run services that scale from nothing to very large without owning a single server. Used carelessly, it can become a public, over-scaled, over-privileged, and surprisingly expensive set of containers. The difference is not luck; it is the habits described in this guide.