This page lists key requirements and behaviors of containers in Cloud Run. There are a few differences between Cloud Run services and Cloud Run jobs: these are called out where appropriate.
Supported languages and images
Your container image can run code written in the programming language of your choice and use any base image, provided that it respects the constraints listed in this page.
Executables in the container image must be compiled for Linux 64-bit. Cloud Run specifically supports the Linux x86_64 ABI format.
Cloud Run accepts container images in the Docker Image Manifest V2, Schema 1, Schema 2, and OCI image formats.
If deploying a multi-architecture image,
the manifest list
must include amd64/linux.
Listening for requests on the correct port (services)
For Cloud Run services, the container must listen for requests on
0.0.0.0 on the port to which
requests are sent. By default, requests are sent to 8080, but you can
configure Cloud Run
to send requests to the port of your choice. Cloud Run injects the
PORT environment variable into the container. Inside Cloud Run container
instances, the value of the PORT environment variable always reflects the port
to which requests are sent. It defaults to 8080.
Container running in a job execution must exit upon completion
For Cloud Run jobs, the container must exit with exit code 0 when the job has successfully completed, and exit with a non-zero exit code when the job has failed.
Because jobs should not serve requests, the container should not listen on a port or start a web server.
Transport layer encryption (TLS)
The container should not implement any transport layer security directly. TLS is terminated by Cloud Run for HTTPS and gRPC, and then requests are proxied as HTTP/1 or gRPC to the container without TLS.
If you configure a Cloud Run service to use HTTP/2 end-to-end, your container must handle requests in HTTP/2 cleartext (h2c) format, because TLS is still terminated automatically by Cloud Run.
Responses (services)
For Cloud Run services, your container instance must send a response within the time specified in the request timeout setting after it receives a request, including the container instance startup time. Otherwise the request is ended and a 504 error is returned.
Environment variables
Different sets of environment variables are available for Cloud Run services and jobs.
Environment variables for services
The following environment variables are automatically added to the running containers:
| Name | Description | Example |
|---|---|---|
PORT |
The port your HTTP server should listen on. | 8080 |
K_SERVICE |
The name of the Cloud Run service being run. | hello-world |
K_REVISION |
The name of the Cloud Run revision being run. | hello-world.1 |
K_CONFIGURATION |
The name of the Cloud Run configuration that created the revision. | hello-world |
Environment variables for jobs
For Cloud Run jobs, the following environment variables are set:
| Name | Description | Example |
|---|---|---|
CLOUD_RUN_JOB |
The name of the Cloud Run job being run. | hello-world |
CLOUD_RUN_EXECUTION |
The name of the Cloud Run execution being run. | hello-world-abc |
CLOUD_RUN_TASK_INDEX |
For each task, this will be set to a unique value between 0 and the number of tasks minus 1. | 0 |
CLOUD_RUN_TASK_ATTEMPT |
The number of times this task has been retried. Starts at 0 for the first attempt; increments by 1 for every successive retry, up to the maximum retries value. | 0 |
CLOUD_RUN_TASK_COUNT |
The number of tasks defined in the --tasks parameter. |
1 |
Request and response header requirements (services)
For Cloud Run services, header names are restricted to printable non-whitespace ASCII, and cannot contain colons. Header values are restricted to visible ASCII characters plus space and horizontal tab as per IETF RFC 7230
Filesystem access
The filesystem of your container is writable and is subject to the following behavior:
- This is an in-memory filesystem, so writing to it uses the container instance's memory.
- Data written to the filesystem does not persist when the container instance is stopped.
Container instance lifecycle
Lifecycle characteristics differ for Cloud Run jobs and services, so these are described separately in the following subsections.
For services
The following apply to services only.
Service scaling
For Cloud Run services, in response to incoming requests, a service is automatically scaled out to a certain number of container instances, each of which runs the deployed container image.
When a revision does not receive any traffic, it is scaled in to the minimum number of container instances configured (zero by default).
Startup
For Cloud Run services, your container instances must listen for requests within 4 minutes after being started. During this startup time, container instances are allocated CPU. You can enable startup CPU boost to temporarily increase CPU allocation during container instance startup in order to reduce startup latency.
Requests will be sent to the container instance as soon as it is listening on the configured port.
A request waiting for a container instance to start will be kept in a queue for a maximum of 10 seconds.
You can configure a startup probe to determine whether the container has started and is ready to serve requests.
Processing a request
For Cloud Run services, CPU is always allocated when the container instance is processing at least one request.
Idle
For Cloud Run services, an idle container instance is one that is not processing any requests.
The CPU allocated to an idle container instance depends on the configured CPU allocation.
Unless a container instance must be kept idle due to the minimum number of container instances configuration setting, it will not be kept idle for longer than 15 minutes.
Shutdown
For Cloud Run services, an idle container instance can be shut down at any time, including container instances kept warm via a minimum number of instances. If a container instance that is processing requests needs to be shut down, new incoming requests are routed to other instances and requests currently being processed are given time to complete. In exceptional cases, Cloud Run might initiate a shutdown and send a SIGTERM signal to an instance that is still processing requests.
Before shutting down a container instance, Cloud Run sends a SIGTERM signal,
indicating the start of a 10 second period
before the actual shutdown occurs, at which point Cloud Run sends a SIGKILL signal.
During this period, the container instance is allocated CPU and billed.
In services that use the first generation execution environment, if the container
instance does not trap the SIGTERM signal, it is
immediately shut down. (Refer to the code samples
to learn how to trap the SIGTERM signal.)
Forced termination
A Cloud Run container instance that exceeds the
allowed memory limit
is terminated. All requests that are still processing on the container instance
end with an HTTP 500 error.
For jobs
For Cloud Run jobs, container instances run until the container instance exits, or until the task timeout is reached or until the container crashes.
Forced termination
A Cloud Run container instance that exceeds the
allowed memory limit
is terminated. All requests that are still processing on the container instance
end with an HTTP 500 error.
If a task exceeds the task timeout,
Cloud Run sends a 'SIGTERM' signal indicating the start of a
10 second period before the actual shutdown
occurs, at which point Cloud Run sends a
SIGKILL signal, shutting down the container instance.
During this period, container instances are allocated CPU for their entire lifecycle and are billed.
Refer to the SIGTERM code sample
to learn how to trap the SIGTERM signal.
Container instance resources
CPU
Each Cloud Run container instance by default gets allocated the vCPU that has been configured (1 by default).
A vCPU is implemented as an abstraction of underlying hardware to provide the approximate equivalent CPU time of a single hardware hyper-thread on variable CPU platforms. All CPU platforms used by Cloud Run support the AVX2 instruction set. Note that the container contract does not contain any additional CPU platform details.
The container instance may be executed on multiple cores simultaneously.
For Cloud Run services, you can specify CPU to be always allocated during the life of the instance or to be only allocated during container instance startup and request processing. Refer to CPU allocation for details.
If you have configured a number of minimum instances, these instances are also subject to the CPU allocation configuration.
You can enable startup CPU boost to temporarily increase CPU allocation during container instance startup in order to reduce startup latency.
Memory
Each Cloud Run container instance by default gets allocated the memory that has been configured, (512 MiB by default).
Typical uses of memory include:
- Code loaded into memory to run the service
- Writing to the filesystem
- Extra processes running in the container such as an nginx server
- In-memory caching systems such as the PHP OpCache
- Per request memory usage
Concurrency (services)
For Cloud Run services, each Cloud Run container instance by default is set to multiple concurrency, where each container instance can receive more than one request at the same time. You can change this by setting concurrency.
Container instance sandbox
If you use the first generation execution environment, the Cloud Run container instances are sandboxed using the gVisor container runtime sandbox. As documented in the gVisor syscall compatibility reference, some system calls might not be supported by this container sandbox.
If you use the second generation execution environment,
you have full Linux compatibility.
Cloud Run jobs always use the second generation execution environment.
Within the second generation execution environment,
/sys/class/dmi/id/product_name is set to Google Compute Engine.
The second generation execution environment runs your service code in a separate process namespace, so it starts as the container init process which has special process semantics. In the first generation execution environment, your service code does not run as the container init process.
Container instance metadata server
Cloud Run container instances expose a metadata server that you can use to retrieve details about your container instance, such as the project ID, region, instance ID or service accounts. It can also be used to generate tokens for the runtime service account.
You can access this data from the metadata server using simple HTTP requests to the
http://metadata.google.internal/ endpoint with the Metadata-Flavor: Google
header: no client libraries are required. For more information, see
Getting metadata.
The following table lists some of the available metadata server information:
| Path | Description |
|---|---|
/computeMetadata/v1/project/project-id |
Project ID of the project the Cloud Run service or job belongs to |
/computeMetadata/v1/project/numeric-project-id |
Project number of the project the Cloud Run service or job belongs to |
/computeMetadata/v1/instance/region |
Region of this Cloud Run service or job, returns projects/PROJECT-NUMBER/regions/REGION |
/computeMetadata/v1/instance/id |
Unique identifier of the container instance (also available in logs). |
/computeMetadata/v1/instance/service-accounts/default/email |
Email for the runtime service account of this Cloud Run service or job. |
/computeMetadata/v1/instance/service-accounts/default/token |
Generates an OAuth2 access token for the service account of this Cloud Run service or job. The Cloud Run service agent is used to fetch a token. This endpoint will return a JSON response with an access_token attribute. Read more about how to extract and use this access token. |
Note that Cloud Run does not provide details about which
Google Cloud zone the container instances
are running in. As a consequence, the metadata attribute /computeMetadata/v1/instance/zone
always returns projects/PROJECT-NUMBER/zones/REGION-1.
File names
File names used in the container must be UTF-8 compatible: either UTF-8 or something that can be safely auto-converted to UTF-8, otherwise, the container image may fail to deploy. This restriction applies only to file names: there's no restriction on the character encoding used in file content.
If you use file names with other encodings, you must convert those filenames to UTF-8 before attempting to deploy.
Outbound connections
Outbound request timeouts
For Cloud Run services and jobs, there is a timeout after 10 minutes of idle time for requests from your container to VPC. For requests from your container to the internet, there is a timeout after 20 minutes of idle time.
Outbound connection resets
Connection streams from your container to both VPC and internet can be occasionally terminated and replaced when underlying infrastructure is restarted or updated. If your application reuses long-lived connections, we recommend that you configure your application to re-establish connections to avoid the reuse of a dead connection.