Container runtime contract

This page lists key requirements and behaviors of containers in Cloud Run.

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 and Schema 2 image formats. The OCI Image Format is not supported at this time.

Listening for requests on the correct port

The container must listen for requests on 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.

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 or gRPC to the container without TLS.


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.

A container instance is terminated if it returns more than 20 5xx sequential responses.

Environment variables

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

Request and response header requirements

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

In response to incoming requests, a service is automatically scaled 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).


Your container instances must listen for requests within 4 minutes after being started. During this startup time, container instances are allocated CPU.

A request waiting for a container instance to start will be kept in a queue for a maximum of 10 seconds.

Processing a request

CPU is always allocated when the container instance is processing at least one request.


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.


A container instance can be shut down at any time, including container instances kept warm via a minimum number of instances.

When a container instance needs to be shut down, new incoming requests are routed to other instances and requests currently being processed are given time to complete. The container instance then receives a SIGTERM signal indicating the start of a 10 second period before being shut down (with a SIGKILL signal). During this period, the container instance is allocated CPU and billed. If the container instance does not catch the SIGTERM signal, it is immediately shut down.

Container instance resources


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. The container instance may be executed on multiple cores simultaneously.

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.


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


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 rather than the system call emulation provided by gVisor.

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 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 belongs to
/computeMetadata/v1/project/numeric-project-id Project number of the project the Cloud Run service belongs to
/computeMetadata/v1/instance/region Region of this Cloud Run service, 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/token Generates a token for the runtime service account of this Cloud Run service. The Cloud Run service agent is used to fetch a 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 request timeouts

For requests from your container to VPC, there is a timeout after 2 minutes of idle time. For requests from your container to the internet, there is a timeout after 20 minutes of idle time.