Cloud Run is a managed compute platform that lets you run containers directly on top of Google's scalable infrastructure.
You can deploy code written in any programming language on Cloud Run if you can build a container image from it. In fact, building container images is optional. If you're using Go, Node.js, Python, Java, .NET Core, or Ruby, you can use the source-based deployment option that builds the container for you, using the best practices for the language you're using.
Google has built Cloud Run to work well together with other services on Google Cloud, so you can build full-featured applications.
In short, Cloud Run allows developers to spend their time writing their code, and very little time operating, configuring, and scaling their Cloud Run service. You don't have to create a cluster or manage infrastructure in order to be productive with Cloud Run.
Services and jobs: two ways to run your code
On Cloud Run, your code can either run continuously as a service or as a job. Both services and jobs run in the same environment and can use the same integrations with other services on Google Cloud.
- Cloud Run services. Used to run code that responds to web requests, or events.
- Cloud Run jobs. Used to run code that performs work (a job) and quits when the work is done.
Cloud Run services
A Cloud Run service provides you with the infrastructure required to run a reliable HTTPS endpoint. Your responsibility is to make sure your code listens on a TCP port and handles HTTP requests.
Standard service features include:
- Unique HTTPS endpoint for every service
- Every Cloud Run service is provided with an HTTPS endpoint on a unique subdomain of the
*.run.appdomain – and you can configure custom domains as well. Cloud Run manages TLS for you, and includes support for WebSockets, HTTP/2 (end-to-end), and gRPC (end-to-end).
- Fast request-based auto scaling
- Cloud Run is built to rapidly scale out to handle all incoming requests. A service can rapidly scale out to one thousand instances, or even more if you request a quota increase. If demand decreases, Cloud Run removes idle containers. If you're concerned about costs or overloading downstream systems, you can limit the maximum number of instances.
- Built-in traffic management
- Every deployment creates a new immutable revision. You can route incoming traffic to the latest revision, roll back to a previous revision, or split traffic to multiple revisions at the same time, to perform a gradual rollout. This is useful if you want to reduce the risk of deploying a new revision. You can start with sending 1% of requests to a new revision, and increase that percentage while monitoring telemetry.
- Private and public services
- A Cloud Run service can be reachable from the internet, or you can restrict access in three ways:
- Specify an access policy using Cloud IAM.
- Use ingress settings to restrict network access. This is useful if you want to allow only internal traffic from the VPC and internal services.
- Allow only authenticated users with Cloud Identity-Aware Proxy (IAP).
You can front a Cloud Run service with a Content Delivery Network (CDN) to serve cacheable assets from an edge location closer to clients. Both Firebase Hosting and Cloud CDN provide this capability.
Scale to zero and minimum instances
Cloud Run adds and removes instances automatically to handle all incoming requests. If there are no incoming requests to your service, even the last remaining instance will be removed. This behavior is commonly referred to as scale to zero.
If there are no active instances, a new instance is created on-demand as soon as a request comes in. This negatively impacts the response time for these first requests, depending on how fast your container becomes ready to handle requests.
To make sure your service doesn't scale scale to zero instances, you can configure Cloud Run to keep a minimum amount of instances active.
Pay-per-use pricing for services
Scale to zero is attractive for economic reasons since you're charged for the CPU and memory allocated to an instance with a granularity of 100ms. If you don't configure minimum instances, you're not charged if your service is not used.
There are two pricing models you can enable:
- If an instance is not processing requests, the CPU is not allocated and you're not charged. Additionally, you pay a per-request fee.
- You're charged for the entire lifetime of an instance and the CPU is always allocated. There's no per-request fee.
There is a generous free-tier. Refer to pricing for more information, and refer to CPU allocation to learn how to enable request-based or instance-based pricing for your service.
A disposable container filesystem
Instances on Cloud Run are disposable. Every container has an in-memory, writable filesystem overlay, which is not persisted if the container shuts down. Cloud Run decides independently when to stop sending requests to an instance and shut it down, for example when scaling in.
To receive a warning when Cloud Run is about to shut down an instance, your application can trap the SIGTERM signal. This enables your code to flush local buffers and persist local data to an external data store.
To persist files permanently, you can integrate with Cloud Storage or mount a network filesystem (NFS).
When to use Cloud Run services
Cloud Run services are great for code that handles requests or events. Example use cases include:
- Websites and web applications
- Build your web app using your favorite stack, access your SQL database, and render dynamic HTML pages.
- APIs and microservices
- You can build a REST API, or a GraphQL API or private microservices that communicate over HTTP or gRPC.
- Streaming data processing
- Cloud Run services can receive messages from Pub/Sub push subscriptions and events from Eventarc.
Cloud Run Jobs
If your code performs work and then stops (a script is a good example), you can use a Cloud Run job to run your code. You can execute a job from the command line using the gcloud CLI, schedule a recurring job, or run it as part of a workflow.
Array jobs are a faster way to run jobs
A job can start one instance to run your code — that's a common way to run a script or a tool. However, you can also start many identical, independent instances in parallel, that is, an array job.
Array jobs are a faster way to process jobs that can be split into multiple independent tasks, as shown here:
For example, if you are reading 1,000 images from Cloud Storage to resize and crop them, processing them consecutively will be slower than processing them all at the same time with many instances.
When to use Cloud Run jobs
Cloud Run jobs are well-suited to run code that performs work (a job) and quits when the work is done. Here are a few examples:
- Script or tool
- Run a script to perform database migrations or other operational tasks.
- Array job
- Perform highly parallelized processing of all files in a Cloud Storage bucket.
- Scheduled job
- Create and send invoices at regular intervals, or save the results of a database query as XML and upload the file every few hours.
Cloud Run integrations
Cloud Run integrates with the broader ecosystem of Google Cloud, which enables you to build full-featured applications.
Essential integrations include:
- Data storage
- Cloud Run integrates with Cloud SQL (managed MySQL, PostgreSQL, and SQL Server), Memorystore (managed Redis and Memcached), Firestore, Cloud Spanner, Cloud Storage, and more. Refer to Data storage for a complete list.
- Logging and error reporting
- Container logs are automatically ingested by Cloud Logging. If there are exceptions in the logs, Error Reporting aggregates them, and then notifies you. The following languages are supported: Go, Java, Node.js, PHP, Python, Ruby, and .NET.
- Service identity
- Every Cloud Run revision is linked to a service account, and the Google Cloud client libraries transparently use this service account to authenticate with Google Cloud APIs.
- Continuous delivery
- If you store your source code in GitHub, Bitbucket, or Cloud Source Repositories, you can configure Cloud Run to automatically deploy new commits.
- Private networking
- Cloud Run instances can reach resources in the Virtual Private Cloud (VPC) network through the serverless VPC access connector. This is how your service can connect with Compute Engine virtual machines or products based on Compute Engine, such as Google Kubernetes Engine or Memorystore.
- Google Cloud APIs
- Your service's code transparently authenticates with Google Cloud APIs. Examples include the AI and Machine Learning APIs, such as the Cloud Vision API, Speech-to-Text API, AutoML Natural Language API, Cloud Translation API, and many more.
- Background tasks
- If you want to schedule code to run later or immediately after returning a web request, Cloud Run works well together with Cloud Tasks to provide scalable and reliable asynchronous execution.
Refer to Connecting to Google Cloud services for a list of all Google Cloud services that work well with Cloud Run.
Services or jobs must be packaged in a container image
In order for your service or job to be deployable to Cloud Run, you must package it in a container image. In case you're not familiar with containers, here's a short conceptual introduction.
Advanced practitioners value the fact that Cloud Run does not impose extra burdens on running their code: you can run any binary on Cloud Run. For users, including experts, who are looking for more convenience, or want to delegate containerizing their application to Google, Cloud Run integrates with the open source Google Cloud Buildpacks to offer a source-based deployment.
- Deploy a Cloud Run service
- Create and execute a Cloud Run job
- Learn how to execute jobs on a schedule
- Explore the resource model
- Read more about the container runtime contract