This page lists key requirements and behaviors of containers inCloud Run. The page also calls out the differences between Cloud Runservices, Cloud Run jobs, and Cloud Run worker pools where appropriate.

Supported languages and images

Your container image can run code written in the programming language of yourchoice and use any base image, provided that it respects the constraintslisted 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, andOCI image formats.Cloud Run also accepts Zstd compressed container images.

If deploying amulti-architecture image,themanifest listmust includelinux/amd64.

For functions deployed with Cloud Run, you can use one of theCloud Run runtime base imagesthat are published by Google Cloud's buildpacks to receive automatic security andmaintenance updates. See theRuntime support schedule the supported runtimes.

Container requirements

When deploying containers to Cloud Run, the following requirements mustbe met:

Container deployed to services must listen for requests on the correct port

A Cloud Run service starts Cloud Runinstances to handle incoming requests.A Cloud Run instance always has one single ingress container that listens forrequests, and optionally one or more sidecar containers. The following portconfiguration details apply only to the ingress container, not to sidecars.

The ingress container within an instance must listen for requests on0.0.0.0 on the port to which requests are sent.Notably, the ingress container shouldnot listen on127.0.0.1.By default, requests are sent to8080, but you canconfigure Cloud Runto send requests to the port of your choice. Cloud Run injects thePORT environment variable into the ingress container.

VPC network connectivity

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Cloud Run services and jobs supportDirect VPCegress. This means that they can sendtraffic to private resources within your configured VPC network, such asdatabases or internal services. Cloud Run services and jobs don'tsupport Direct VPCingress.

Cloud Run worker pools support both Direct VPCegress and Direct VPCingress. When you configure Direct VPCfor your Cloud Run worker pool deployment, each workerinstance receives a private IP address on the configured network and subnet.Only resources from your VPC network can connect to the worker pool private IP address endpoint.For more information about obtaining the private IP addresses of your worker poolinstance, seeRetrieve the private IP addresses using the metadata server(MDS).

For Cloud Run worker pools with Direct VPC ingress, such as databaseconnections or any other custom TCP-based protocol, the container must listenfor TCP connections on the port exposed in your container image through theDockerfile or specified by thePORT environment variable.

Container running in a job execution must exit upon completion

For Cloud Run jobs, the container must exit with exit code 0 when thejob has successfully completed, and exit with a non-zero exit code when the jobhas failed.

Because jobs shouldn't serve requests, the container shouldn't listen on a port orstart a web server.

Transport layer encryption (TLS)

The container shouldn't implement any transport layer security directly. TLS isterminated by Cloud Run for HTTPS and gRPC, and then requests are proxied asHTTP/1 or gRPC to the container without TLS.

If youconfigure a Cloud Run service touse 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 must send a responsewithin the time specified in therequest timeout setting after itreceives a request, including the container startup time.Otherwise the request is ended and a 504 error is returned.

Response caching and cookies

If your Cloud Run service's response contains aSet-Cookieheader, Cloud Run sets theCache-Control header toprivate sothat the response is not cached. This prevents other users from retrieving thecookie.

Environment variables

Different sets of environment variables are available for Cloud Runservices and jobs.

Environment variables for services

The following environment variables are automatically added to all the runningcontainers exceptPORT. ThePORT variable is only added to the ingress container:

Environment variables for jobs

For Cloud Run jobs, the following environment variables are set:

Environment variables for worker pools

Cloud Run sets the following environment variables for worker pools:

Request and response header requirements (services)

For services, Cloud Run restricts header names to printable non-whitespace ASCII, and cannotcontain colons. Cloud Run restricts header values to visible ASCII characters, plusspace and horizontal tab, according toIETF RFC 7230.

File system access

Each container's file system is writable and subject to the followingbehavior:

• It is an in-memory file system, so writing to it uses theinstance's memory.
• Data written to the file system doesn't persist when the instance stops.

You cannot specify a size limit for this files system, so you canpotentially use up all the memory allocated to your instance by writingto the in-memory file system, which will crash the instance. You can avoid thisissue if you use a dedicatedin-memory volumewith a size limit.

Instance lifecycle

Lifecycle characteristics differ for Cloud Run jobs and services, sothese are described separately in the following subsections.

For services

The following characteristics apply to services only.

Service scaling

By default, a Cloud Run service isautomatically scaled to the number ofinstances needed to handle all incoming requests, events, orCPU utilization. You can optionally usemanual scalingif you need more control over your scaling behavior.

Every instance runs a fixed numberof containers – one ingress container and optionally one or more sidecar containers.

When a revision does not receive any traffic, it is scaled in to theminimum number of instances configured(zero by default).

Startup

For Cloud Run services, your instances must listen for requests within4 minutes after being started and all containers withinthe instance need to be healthy.During this startup time, instances are allocated CPU. You canenable startup CPU boost totemporarily increase CPU allocation during instance startup in orderto reduce startup latency.

Requests will be sent to the ingress container as soon as it islistening onthe configured port.

A request waiting for an instance will be kept pending in a queue asfollows:

Requests will pend for up to 3.5 times average startup time of container instances of this service, or 10 seconds, whichever is greater.

You can configure astartup probe todetermine whether the container has started and is ready to serve requests.

For a Cloud Run service consisting of multi-container instances, you can specify the sequence in whichthe containers are started within the instance by configuring thecontainer startup order.

Processing a request

For Cloud Run services, CPU is always allocated to all containersincluding sidecars within an instance as long as the Cloud Runrevision is processing at least one request.

Idle

For Cloud Run services, an idle instance is one that is notprocessing any requests.

The CPU allocated to all containers in an idle instance depends on theconfiguredbilling settings.

Unless an instance must be kept idle due totheminimum number of instancesconfiguration setting, it won't be kept idle for longer than 15 minutes.

Shutdown

For Cloud Run services, an idle instance can be shut down at any time, includinginstances kept warm due to a configured minimum number of instances.If an instance that is processing requests needs to be shut down,requests already being processed are given time to complete, and new incoming requests are routed to other instances. In exceptional cases, Cloud Run might initiate a shutdown and send aSIGTERM signal to a container that is still processing requests.

Before shutting down an instance, Cloud Run sends aSIGTERM signal to all the containers in an instance,indicating the start of a 10 second periodbefore the actual shutdown occurs, at which point Cloud Run sends aSIGKILL signal.During this period, the instance is allocated CPU and billed.In services that use the first generation execution environment, if theinstance does not trap theSIGTERM signal, it isimmediately shut down. In services that use the second generation executionenvironment, we recommend installing aSIGTERM handler onyour container to receive a warning when Cloud Run is about to shutdown an instance.

Forced termination

If one or more Cloud Run containers exceed thetotal container memory limit,the instance is terminated. All requests that are still processing on the instanceend with anHTTP 500 error.

For jobs

For Cloud Run jobs, container instances run until the containerinstance exits, or until thetask timeoutis reached or until the container crashes.

Exit codes

You can use job exit codes to see whether the job completed successfully orwhether it encountered any errors. The exit codes are numerical values that mapto successful completion or specific types of errors.

The following table specifies common exit codes and their definitions:

Forced termination

A Cloud Run container instance that exceeds theallowed memory limitis terminated. All requests that are still processing on the container instanceend with anHTTP 500 error.

If a task exceeds thetask timeout,Cloud Run sends a 'SIGTERM' signal indicating the start of a10 second period before the actual shutdownoccurs, at which point Cloud Run sends aSIGKILL signal, shutting down the container instance.

During this period, container instances are allocated CPU for their entirelifecycle and are billed.

Refer tothe SIGTERM code sampleto learn how to trap theSIGTERM signal.

For worker pools

The following characteristics apply only to worker pools.

Scaling

Worker pools don't automatically scale.Manuallyscale the number of instancesthat your Cloud Run worker pool requires to handle its workload. Bydefault, Cloud Run sets the number of instances to1. You can changethis number to be higher or lower, or you can disable scaling by setting thenumber to 0. To start and remain active, your workload must have at least oneinstance. If you set the minimum instances to0, the worker instance won'tstart, even if the deployment is successful.

Startup

Cloud Run worker pools instances start the container withthe entrypoint you specify in the container image or in the worker poolconfiguration. All containers in the instance must be healthy.

By default, Cloud Run container instances use one CPU. You canincrease or decrease this value basedon your requirements.

You can configure astartup probeto determine whether the container started.The startup probe enables Cloud Run to inspect the health of a dependentcontainer, making sure it passes successfully before it starts up the next container.If you don't use health checks, Cloud Run starts containers in thespecified order, even if containers they depend on fail to start.

Resource allocation

Worker pools don't idle. Regardless ofits state, Cloud Run always allocates CPU to to all containers,including sidecars within a worker pool instance.As long as it's running, an instance is considered active and is billedaccordingly.

Shutdown

Cloud Run doesn't scale down worker pool instances based on idleinstances. If a workload-processing instance must be shut down,Cloud Run gives tasks in-process tasks time to complete androutes new workloads to other instances. Cloud Runmight also initiate a shutdown and send aSIGTERM signal to a container that is stillprocessing a workload.

Before shutting down an instance, Cloud Run sends aSIGTERM signalto all the containers in an instance. This signal indicates the start of a 10-second period before the actual shutdownoccurs, at which point Cloud Run sends aSIGKILL signal.During this shutdown period, the instance is allocated CPU and billed.We recommend installing aSIGTERM handler onyour container to receive a warning when Cloud Run is about to shutdown an instance.

Forced termination

If one or more Cloud Run containers exceed thetotal container memory limit,Cloud Run terminates the instance. All requests that are stillprocessing on the instance end with anHTTP 500 error.

Container instance resources

Your container runs under a cgroup controller that restricts CPU, RAM, and otherresources to those configured for your container.

The following sections describe resources for your container instance:

• CPU
• Memory
• GPU
• Concurrency

CPU

Each Cloud Run container in an instance by default gets allocated thevCPUthat has beenconfigured(1 by default). It is possible to configure CPU limits on each container separately.

A vCPU is implemented as an abstraction of underlyinghardware to provide the approximate equivalent CPU time of a single hardwarehyper-thread on variable CPU platforms. All CPU platforms used by Cloud Runsupport theAVX2instruction set. Note that the container contract does not contain any additional CPU platform details.

The container might be executed on multiple cores simultaneously.

For Cloud Run services, CPU allocation depends on theselected billing.

If you select instance-based billing, CPU is allocated during the life of theinstance. If you select request-based billing (default), CPU is allocated wheninstances are processing requests. Refer tobilling settings for details.

If you have configured a number ofminimum instances, you must useinstance-based billing so that CPU is allocatedoutside of requests.

You canenable startup CPU boost totemporarily increase CPU allocation during instance startup in orderto reduce startup latency.

Memory

Each Cloud Run container by default gets allocated the memorythat has beenconfigured,(512 MiB by default). It is possible to configure memory limits on each container separately.

Typical uses of memory include:

• Code loaded into memory to run the service
• Writing to the file system
• Extra processes running in the container such as an nginx server
• In-memory caching systems such as the PHPOpCache
• Per request memory usage
• Shared in-memory volumes

GPU

You can configure a container in a Cloud Run instance to access a GPU.If the Cloud Run service is deployed withsidecar containers, only one container in the deployment can access the GPU. SeeConfigure GPU for requirements and details.

NVIDIA libraries

By default, all of the NVIDIA L4 and NVIDIA RTX PRO 6000 Blackwell GPU driver librariesare mounted under/usr/local/nvidia/lib64. Cloud Run automaticallyappends this path to theLD_LIBRARY_PATH environment variable(i.e.${LD_LIBRARY_PATH}:/usr/local/nvidia/lib64) of the container with theGPU. This allows the dynamic linker to find the NVIDIA driver libraries. Thelinker searches and resolves paths in the order you list in theLD_LIBRARY_PATHenvironment variable. Any values you specify in this variable take precedenceover the default Cloud Run driver libraries path/usr/local/nvidia/lib64.

If you want to use a CUDA version greater than 12.2,the easiest way is to depend on a newerNVIDIA base imagewith forward compatibility packages already installed. Another option is tomanuallyinstall the NVIDIA forward compatibility packagesand add them toLD_LIBRARY_PATH. ConsultNVIDIA's compatibility matrixto determine which CUDA versions are forward compatible with the provided NVIDIAdriver version.

Concurrency (services)

For Cloud Run services, each Cloud Run instance by default is set to multipleconcurrency,where the ingress container can receive more than one request at the same time.You can change this bysetting concurrency.

Container security restrictions

The following restrictions apply to containers that run in Cloud Run.They apply regardless of the Linux user that the container image specifies forexecution.

Reduced privileges

In Cloud Run, your containers are not granted the rootcapabilities of the instance's security boundary. Containers cannot perform actions reservedfor the host, such as the following:

• Adding or removing Linux kernel capabilities
• Using specific kernel capabilities
• Manipulating devices
• Accessing certain hardware resources

Privilege escalation is also disabled in your containers. Use ofsudo andsetuid binaries are not supported in Cloud Run.

Your containers won't have write access to most of the files and directories in/dev,/proc, and/sys.

There is no Cloud Run equivalent to Docker's--privileged mode.

Container isolation

Cloud Run executes your containers under user, network, PID, andother Linux namespaces, isolating them from each other and from the instanceitself. This restricts some network capabilities and prevents your rootcontainers from running as "true root."

Limited file system mounts from inside containers

The supported path for mounting file systems in Cloud Run isthrough thefully managed volume mounts feature in your Cloud Run container configuration.

Other mechanisms of mounting from inside user containers are not supported andwon't work. Unsupported mechanisms include, but aren't limited to, the following:

• Running a mount process inside the container to mount any of the following:NFS, Filestore, SMB/CIFS, or any other network file system.
• Calling system calls that would perform equivalent actions.

In addition, Cloud Run doesn't support nested volume mounts thatmount one volume inside of another volume.

No alterations to system time

Changing the system time usingadjtimex andadjtime system calls is notsupported, nor are any tools that might permit your container to do so.

Process and system call restrictions

Basic security profiles, similar toseccomp security profiles for Docker,are applied around each of your containers.

Use of eBPF and other kernel-level security features that aren't protected orlimited by Linux namespaces are disabled and not supported for use insidecontainers.

Use of other system calls or access system files that require root privileges onthe Cloud Run instance might also be restricted for this reason.

Container sandbox

If you use thefirst generation execution environment,the Cloud Run containers are sandboxed usingthegVisor container runtime sandbox.As documented in thegVisor syscall compatibility reference,some system calls might not be supported by this container sandbox.

If you use thesecond 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 toGoogle Compute Engine.

The second generation execution environment runs your service code in a separateprocess namespace, so it starts as the container init process which has specialprocess semantics. In the first generation execution environment, your servicecode does not run as the container init process.

File descriptor limits

Cloud Run first and second generation environments set a limit onthe number of file descriptors a process can open to25000. This applies to the container and anychild process it creates (forks).This is a hard limit. If you exceed the limit your instance might run out offile descriptors/sockets.

Limits in the second generation environment

Except for the file descriptor limits described earlier,limits in the second generation environment are standard linux limits.

For example, the limits on the number of file descriptors that can beopened (as captured in:/proc/sys/fs/file-max) use the default value of about10% of memory. Seefile-max andfile-nrin the kernel documentation for details.

Similarly, themax_map_count (as captured in/proc/sys/vm/max_map_count),which sets the number of memory areas a process can have is using the defaultof 65535. Seemax-map-countin the kernel documentation for details.

Privileged containers and setuid binaries

Cloud Run doesn't supportprivileged containers. Consequently, Cloud Run doesn't support binaries that usesetuid flags for non-root users, such asgcsfuseorsudo, and might fail due to insufficient permissions.

One alternative is to execute these binaries as the root user andthen use thesu command to switch to another user at runtime.

For example, in your Dockerfile, remove theUSER instruction, and in yourentrypoint script, use the following sequence:

gcsfuse...# Run gcsfuse as rootsumyuser-c"/yourapp.sh"# Switch to 'myuser' and run 'yourapp.sh'

Executing user

If theuser name doesn'texist, Cloud Run runs the container as the root user (uid=0).

Communication between containers of the same instance

Cloud Run adds an entry to the/etc/hosts file in eachcontainer. This entry maps the service names to the localhost IP address(127.0.0.1). This lets containers communicate with each other using theircontainer name.

Instance metadata server

Cloud Run instances expose a metadata server that you can useto retrieve details about your containers, such as the project ID,region, instance ID or service accounts. You can also use the metadata server togenerate tokens for the service identity.

To access metadata server data, use HTTP requests to thehttp://metadata.google.internal/ endpoint with theMetadata-Flavor: Googleheader: no client libraries are required. For more information, seeGetting metadata.

The following table lists some of theavailable metadata server information:

Cloud Run doesn't provide details about whichGoogle Cloud zone the instancesare running in. As a consequence, the metadata attribute/computeMetadata/v1/instance/zonealways returnsprojects/PROJECT-NUMBER/zones/REGION-1.

File names

The file names that you use in containers must be UTF-8 compatible, either UTF-8or something that can be safely auto-converted to UTF-8. If your file names usedifferent encodings, run Docker build on a machine with UTF-8 compatible filenames,and avoid copying files to a container that contains incompatible UTF-8 names.

Container deployment fails if file names are not UTF-8 compatible. Note thatthere's no restriction on the characterencoding you use within a file.

Outbound request timeouts

For Cloud Run services and jobs, there is a timeout after10 minutes of idle time for requests from your container toVPC.For requests from your container to the internet, there is a timeout after20 minutes of idle time.

Outbound connection resets

Connection streams from your container to bothVPC and internet can beoccasionally terminated and replaced when underlying infrastructure is restartedor updated. If your application reuses long-lived connections, werecommend that you configure your application to re-establish connections toavoid the reuse of a dead connection.