Cloud Run is a fully managed service that runs your containerized application and scales it up and down automatically, including all the way down to zero.

The plain-English definition

Cloud Run is a service from Google Cloud that lets you run a program on the internet without ever touching a server. You give it a container image, which is a sealed box that holds your code and everything the code needs to run. Cloud Run starts that box when someone calls it, keeps enough copies running to handle the traffic, and stops them when traffic goes away.

The word serverless does not mean there are no servers. Servers still exist. It means you do not see them, patch them, or pay for them while they sit idle. Google does that work for you.

Why did Google build it?

Before Cloud Run, developers had two main choices. The first was virtual machines, which give you full control but also full responsibility. The second was platforms like App Engine or Cloud Functions, which were easy but forced you to use specific languages, frameworks, or code shapes.

Teams kept asking for a middle road: “Let me use any language, any library, any framework, but still skip the server chores.” Containers made that possible, because a container can hold anything. Cloud Run is the service that takes a container and runs it with serverless simplicity. It is also compatible with the Knative open standard for running containers on Kubernetes, which means the programming model is not locked into a secret Google-only format.

Where is Cloud Run used?

Teams use it for web websites, REST and gRPC APIs, backends for mobile apps, webhook receivers, data processing steps, scheduled background tasks, and glue code that connects other Google Cloud services. It is also the engine behind Google’s own function-style offering, so even if you write small functions, you may already be using Cloud Run without knowing it.

Six simple ideas explain almost everything about Cloud Run. Learn these and the rest will feel natural.

Containers and images

A container is a lightweight, packaged environment that holds your application code, its libraries, and its settings. An image is the saved blueprint of that container. If the image is a recipe card, the container is the dish made from it. The big promise of containers is “it runs the same everywhere”, which stops the classic complaint “but it worked on my laptop!”

Cloud Run pulls your image from a registry. In Google Cloud this is usually Artifact Registry, which is simply a storage shelf for container images.

Services

A service is the main Cloud Run building block. It is a long-lived, named application that answers requests such as web calls. Each service gets its own secure web address that ends in run.app, and you can also attach your own domain name.

Revisions

Every time you deploy a change, Cloud Run creates a new revision. A revision is a frozen snapshot of your code plus its settings. It never changes after it is created. Think of it like the numbered editions of a book: edition one stays exactly as printed, and edition two is a separate thing.

This is powerful because you can send all traffic to the newest revision, or split traffic between old and new, or roll back in seconds by pointing traffic at an older revision.

Instances

An instance is one running copy of your container. When traffic grows, Cloud Run starts more instances. When traffic shrinks, it stops them. One revision can have zero, one, or hundreds of instances running at the same time.

Concurrency

Concurrency means how many requests one instance handles at the same time. This is a special feature of Cloud Run. Many serverless platforms give one request to one instance, which wastes resources. Cloud Run, by default, allows one instance to handle up to 80 requests at once, and you can raise it up to 1,000 or lower it to 1 if your code needs it.

Jobs

A job is the second main building block. Unlike a service, a job does not wait for web requests. It runs a task from start to finish and then stops. Examples include processing a pile of files, sending a batch of emails, or running a database cleanup at midnight.

Let us look at the pieces that sit around a Cloud Run service in a real system.

Cloud Run never works alone. It sits in the middle of a larger picture. Requests come in from the front, your container does its work in the middle, and data is stored at the back. The diagram below shows a typical layout for a production web application.

flowchart LR
  U["Users and Mobile Apps"] --> LB["Global External Load Balancer"]
  LB --> ARM["Cloud Armor Security Rules"]
  ARM --> CR["Cloud Run Service"]
  CR --> R1["Revision 1 Instances"]
  CR --> R2["Revision 2 Instances"]
  R1 --> SQL["Cloud SQL Database"]
  R2 --> SQL
  R1 --> CACHE["Memorystore Cache"]
  R2 --> CACHE
  R1 --> PS["Pub/Sub Topic"]
  PS --> JOB["Cloud Run Job or Worker"]
  R1 --> SM["Secret Manager"]
  R1 --> LOG["Cloud Logging and Monitoring"]
    

Walking through the picture

Users and apps send requests over HTTPS. They could be people in a browser or other programs calling your API.

The global external load balancer is an optional but common front door. It gives you one fixed IP address, lets you serve users from many regions, and plugs into extra protections. Think of it as the reception desk at a big office building.

Cloud Armor is Google’s shield against attacks such as floods of fake traffic and common web exploits. It sits beside the load balancer.

The Cloud Run service holds the rules: which revision gets how much traffic, how many instances may run, and what settings apply.

The instances are the actual running containers. They talk to a database such as Cloud SQL, to a cache such as Memorystore, and to a messaging system called Pub/Sub that lets one part of your system hand work to another part.

Secret Manager stores passwords and keys safely. Cloud Logging and Monitoring collect what your app says and how it behaves.

Where does your container actually run?

Cloud Run runs on Google’s own large-scale infrastructure. Your container runs inside a protected sandbox so that it cannot see or affect other customers’ containers. Cloud Run offers two execution environments: the first generation is optimized for fast startup and uses a strong sandbox layer, while the second generation gives fuller Linux compatibility and better network and file performance. You can choose per service, and picking the right one depends on whether your app needs special Linux features or maximum speed at startup.

Follow one request from the user’s phone to your code and back again.

Understanding the journey of a single request helps you answer many interview questions and fix many real bugs. Here is the path in order.

sequenceDiagram
  participant C as Client
  participant G as Google Front End
  participant R as Cloud Run Router and Autoscaler
  participant W as Warm Instance
  participant N as New Instance
  C->>G: Send HTTPS request
  G->>R: Forward to the right service
  alt A warm instance has free capacity
    R->>W: Send request
    W-->>C: Return response
  else No free capacity
    R->>N: Start a new instance
    N-->>R: Container is ready
    R->>N: Send request
    N-->>C: Return response
  end
    

The one rule your container must follow

Your application must listen for web traffic on the port named in the PORT setting that Cloud Run gives it. By default this is 8080. Your app must also start fast enough to begin listening within the allowed startup time. If it does not, Cloud Run decides the instance failed and tries again. Forgetting this rule is the most common reason a first deployment fails.

What is a cold start?

A cold start is the delay that happens when Cloud Run must start a brand-new instance to serve a request. The container image must be fetched, the container started, and your app must boot. It might take under a second for a small app or several seconds for a heavy one.

Cloud Run decides how many instances to run. Your job is to give it good hints.

How autoscaling decides

Autoscaling means the platform adds or removes instances by itself. Cloud Run mainly watches how busy your current instances are, using two signals: how many requests each instance is handling compared with its concurrency limit, and how much CPU the instances are using. When instances are getting full, it starts more. When instances sit mostly idle, it removes them after a short wait.

This is why concurrency matters so much for cost and speed. If you set concurrency to 1, a thousand simultaneous requests need a thousand instances. If your code can safely handle 80 at once, those same requests may need only about a dozen instances. Fewer instances usually means fewer cold starts and a smaller bill.

The settings that shape performance

Billing styles and what they mean for speed

Cloud Run has two ways to use CPU. In the default request-based style, CPU is only guaranteed while a request is being handled, and you pay only for that time. This is the cheapest choice for spiky traffic. In the instance-based style, CPU stays available the whole time the instance exists, which is useful when your app does background work between requests, but you pay for the full lifetime of each instance.

Making your app scale well

Keep your container image small so it downloads quickly. Start your app fast by delaying heavy work until it is truly needed. Avoid storing user data inside the instance, because the next request may go to a different one. Use connection pooling carefully, because many instances each opening many database connections can overwhelm a database. These small habits separate a smooth production system from a fragile one.

Choose the right shape for the work: answer-on-demand or run-and-finish.

Cloud Run services in detail

Services handle HTTP, HTTPS, gRPC, and streaming connections such as WebSockets. They suit anything that must respond quickly when a user or another system calls. Because services are stateless, they scale easily, but you must keep memory-only data to a minimum.

Cloud Run jobs in detail

A job runs a container to completion. A single job execution can be split into many tasks that run in parallel. Each task knows its own index number, so your code can say “I am task 7 of 50, so I will process the seventh slice of the files.” If a task fails, Cloud Run can retry it. Jobs can run on a schedule using Cloud Scheduler, or be started by a person or by another system.

A single task can run for a long time, up to many hours, which is far beyond what a normal web request allows. This makes jobs the right home for report generation, data migration, image processing, and nightly cleanups.

Cloud Run functions and source deploys

If you do not want to write a container file at all, Cloud Run can build a container for you straight from your source code using Google’s build tools, and it also supports a function-style experience where you write one small function and Google wraps it. The result still runs on Cloud Run underneath.

Releasing new code is the scariest moment of any project. Cloud Run makes it calmer.

The deployment path

A normal flow looks like this. A developer pushes code to a repository. An automated pipeline, often built with Cloud Build or a similar tool, builds the container image and stores it in Artifact Registry. The pipeline then tells Cloud Run to create a new revision from that image. Cloud Run checks the new revision is healthy and then starts sending traffic to it.

Traffic splitting

Because revisions are separate and unchangeable, Cloud Run can send different percentages of traffic to different revisions at the same moment. This enables two famous release styles.

flowchart TD
  T["Service URL"] --> A["Revision 1 receives 90 percent"]
  T --> B["Revision 2 receives 10 percent"]
  B --> M["Watch errors and latency"]
  M -->|Looks healthy| P["Shift to 50 percent then 100 percent"]
  M -->|Looks bad| RB["Send 100 percent back to Revision 1"]
    

Configuration without rebuilding

Settings such as database addresses should come from environment variables, which are named values given to your container at start time. This lets the same image run in testing and in production with different settings. Never bake passwords into the image itself.

By default, Cloud Run lives on the public internet. Real systems often need private connections too.

Ingress: who can call you?

Ingress controls where incoming traffic may come from. You can allow all traffic, allow only traffic from inside your Google Cloud network, or allow only traffic that comes through a Cloud Load Balancer. Choosing a stricter option keeps internal services away from the open internet.

Egress: how do you call out?

Egress is outgoing traffic from your container. By default it goes out to the public internet. If your database or another system lives inside a private network called a VPC (Virtual Private Cloud, your private section of Google’s network), you must give Cloud Run a way in. Two common options are a Serverless VPC Access connector and the newer direct VPC egress, which lets instances join the network without a separate connector machine. Direct egress is usually simpler and cheaper to operate, though you should check which fits your needs.

Custom domains and global reach

A Cloud Run service lives in one region, which is a geographic location such as Mumbai or Iowa. To serve users worldwide with low delay, you can deploy the same service in several regions and put a global load balancer in front. The load balancer sends each user to the nearest healthy region and can fail over if one region has trouble.

Talking to data stores

• Cloud SQL for relational databases, with a built-in secure connection option.
• Firestore for flexible document data.
• Cloud Storage for files, which can also be mounted so your app sees a bucket like a folder.
• Memorystore for fast in-memory caching.
• Pub/Sub and Cloud Tasks for sending work to be done later.

Security is built in layers, like the walls, gate, and guards of a castle.

flowchart TB
  A["Layer 1: Network edge with Load Balancer and Cloud Armor"] --> B["Layer 2: Ingress settings limit who can reach the service"]
  B --> C["Layer 3: IAM checks who is allowed to invoke"]
  C --> D["Layer 4: Container runs as a limited service account"]
  D --> E["Layer 5: Secrets come from Secret Manager"]
  E --> F["Layer 6: Audit logs record who did what"]
    

Who can call your service? (IAM)

IAM, short for Identity and Access Management, is Google Cloud’s permission system. For Cloud Run, a key permission is the invoker role. If a service is public, anyone on the internet may call it. If it is private, only identities that hold the invoker role may call it, and they must send a signed identity token with each request.

A good habit is to make services private by default. Allow public access only for services that truly serve the public, such as a website. Internal microservices should require identity checks, so even if someone finds the address, they cannot use it.

What can your service do? (Service identity)

Each Cloud Run service runs as a service account, which is a robot identity with its own set of permissions. If your service only needs to read one storage bucket, give its service account only that permission. This follows the principle of least privilege, meaning give each part only the access it truly needs. Never run production services with a powerful shared identity just because it is easier.

Handling secrets

Passwords, API keys, and certificates must never sit inside your code or image. Store them in Secret Manager and let Cloud Run hand them to your container as environment variables or as files at start time. Secrets can be rotated, and access to them is logged.

Protecting the supply chain

Your container is only as safe as what is inside it. Scan images for known weaknesses, use small trusted base images, and keep libraries updated. Binary Authorization is a feature that can require images to be signed and approved before Cloud Run will run them, which stops unknown or tampered images from reaching production.

Encryption and compliance

Traffic to Cloud Run uses HTTPS, and data at rest in Google’s services is encrypted by default. Organizations with strict rules can add their own encryption keys and can restrict where services may run. Audit logs record administrative actions so security teams can answer “who changed what and when.”

You cannot fix what you cannot see. Cloud Run gives you eyes from the very first deployment.

Logging

Anything your app prints to its normal output streams is collected automatically by Cloud Logging. Each request also gets an automatic log entry showing the status code, delay, and size. For best results, print logs as structured text with fields such as severity and a request identifier, so you can search them quickly instead of reading walls of text.

Metrics

Cloud Monitoring collects numbers over time. For Cloud Run, the most useful ones are request count, request delay (often looked at as percentiles, such as the time under which 99 out of 100 requests finish), error rate, number of running instances, CPU use, and memory use.

Tracing and error reporting

Cloud Trace follows a single request across several services so you can see which step was slow. Error Reporting groups similar crashes together so you see “this error happened 400 times” instead of 400 separate lines.

Alerts and service goals

Set alerts that tell people when something is wrong, for example when the error rate stays above a limit for several minutes. Better still, define a service level objective (SLO), which is a promise such as “99.9 percent of requests succeed each month.” Cloud Monitoring can track this promise and warn you when you are spending your allowed failures too quickly.

No tool is perfect. A good architect knows both sides before choosing.

How you are charged

Cloud Run charges for the CPU and memory your instances use, rounded up in small time steps, plus a small amount for requests in request-based mode, plus normal network charges when data leaves Google Cloud. There is a free allowance each month, so small projects and experiments often cost almost nothing. Because prices change over time, always check the official pricing page before making budget decisions.

Cloud Run compared with its neighbours

The trade-off in one sentence

Cloud Run trades deep control for simplicity and speed. If your team is small and your workload fits the model, that is a wonderful bargain. If you need custom networking, special hardware control, or long-lived stateful processes, a heavier tool may serve you better.

A design pattern is a proven way to solve a repeated problem. These fit Cloud Run naturally.

Example: queue-based load leveling

Imagine a ticket-booking site during a popular concert sale. A million people click at once. If every click went straight to a database-heavy step, the database would collapse. Instead, the front service accepts the click quickly, places a message on a queue, and answers “we got your request.” A worker service reads messages at a pace the database can handle. Users get a fast reply, and the database stays alive.

Anti-patterns to avoid

Small habits, repeated daily, make the difference between a hobby setup and a production system.

Best practices

• Keep images small. Use minimal base images and remove files you do not need. Smaller images download and start faster.
• Start fast. Delay heavy setup, such as loading large files, until the first time it is required.
• Be stateless. Treat every instance as disposable.
• Handle shutdown politely. When Cloud Run stops an instance, it sends a signal first. Catch it and finish current work cleanly.
• Tune concurrency with testing. Run load tests, then raise or lower the number based on real results, not guesses.
• Set minimum instances only where needed. Use them for user-facing paths that cannot tolerate cold starts.
• Cap maximum instances. Protect downstream systems.
• Use least-privilege service accounts. One identity per service, with minimal rights.
• Automate deployments. Use a pipeline so releases are repeatable and reviewed.
• Use structured logs and health checks. Startup and liveness checks help Cloud Run notice and replace broken instances.
• Make operations safe to repeat. Requests and tasks may be retried, so your code should give the same result if it runs twice. This property is called idempotency.

Common mistakes

Here is how teams commonly apply Cloud Run in practice.

These are common patterns, described in general terms, rather than claims about any one named company’s private setup. They show how the ideas in this guide combine.

Lessons that repeat

Across these scenarios, the same lessons appear again and again: keep services stateless, cap scaling to protect databases, put slow work behind queues, make services private by default, and watch latency and errors from the start.

Quick, clear answers to the questions beginners ask most often.

Not always. If you can write a container file, you have the most control. If not, you can deploy straight from source code and let Google build the container for you. Learning basic container ideas still helps a lot.

No. Services can serve APIs, gRPC, and streaming connections, and jobs can run any batch task that finishes. It is a general-purpose container runner.

With minimum instances left at zero, Cloud Run removes all instances after a quiet period and you stop paying for compute. The next request causes a cold start.

Set a minimum number of instances, keep your image small, start your app quickly, and consider the startup CPU boost. You cannot remove cold starts completely if you scale to zero.

Yes, WebSockets and streaming are supported, but each connection is still a request and is subject to the request timeout, so clients should be ready to reconnect.

You can write temporary files, but they live in memory and vanish when the instance stops. For lasting files, use Cloud Storage or a database. Mounted storage volumes are available when your app expects a folder.

Kubernetes gives you a cluster to design and operate, with great power and great responsibility. Cloud Run hides the cluster and gives you a simple service model. Choose Kubernetes when you need deep control, and Cloud Run when you want speed and simplicity.

Access depends on how you configure it. You can require authentication so only approved identities can call it. Always check the access setting before going live.

Check the logs first. The usual causes are the app not listening on the expected port, the app crashing on startup, or missing permissions to pull the image. Your previous revision keeps serving traffic until the new one is healthy.

For spiky or low traffic, usually yes, because you stop paying when idle. For steady, heavy, always-on loads, reserved machines can sometimes cost less. Do the math for your own traffic shape.

Yes. Use Cloud Scheduler to call a service or start a job at times you choose, such as every night at midnight.

Cloud Run lets you focus on the dish instead of the building. You package your app as a container, Google runs it, scales it, secures the front door, and records what happens. You pay for what you use and learn a small set of ideas: services, jobs, revisions, instances, and concurrency.

Used with care, it fits a huge range of workloads. Used carelessly, it can overload databases, leak access, or surprise you with cold starts. The ideas in this guide give you the map to avoid those traps.