Configure container health checks for worker pools
Preview — Cloud Run worker pools
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.
You can configure HTTP, TCP, and gRPC startup probes, along with HTTPand gRPC liveness probes for new and existing Cloud Run worker pools.The configuration varies depending on the type of probe.
Use cases
You can configure two types of health check probes:
Liveness probes determine whether to restart a container.
- Restarting a container in this case can increase worker pool availability inthe event of bugs.
- Liveness probes are intended to restart individual instances that can't berecovered in any other way. They should be used primarily forunrecoverable instance failures, for example, to catch a deadlock where aworker pool is running, but unable to make progress. You canrequire a liveness probe for every container by usingcustom organization policies.
Startup probes determine whether the container has started.
- When you configure a startup probe, liveness checks are disabled until thestartup probe determines that the container is started, to prevent interferencewith the worker pool startup.
- Startup probes are especially useful if you use liveness checks on slowstarting containers, because it prevents them from being shut downprematurely before the containers are up and running.
Note that when a worker pool experiences repeated startup or liveness probe failures,Cloud Run prevents uncontrolled crash loops by limiting instancerestarts to prevent.
CPU allocation
- CPU is always allocated when probes run.
- All probes are billed for CPU and memory usage consumption.
Probe requirements and behavior
| Probe Type | Requirements | Behavior |
|---|---|---|
| TCP startup | None | If specified, Cloud Run makes a TCP connection to open the TCP Socket on the specified port. If Cloud Run is unable to establish a connection, it indicates a failure. If a startup probe does not succeed within the specified time, Cloud Run shuts down the container. The time is a maximum of 240 seconds, calculated as failureThreshold *periodSeconds, which you set when configuring the startup probe for the worker pool. |
| HTTP startup | Create anHTTP health check endpoint Use HTTP/1 | After probe configuration, Cloud Run makes an HTTP GET request to the worker pool health check endpoint (for example,/ready). Any response between200 and400 is a success, everything else indicates failure.If a startup probe does not succeed within the specified time ( failureThreshold *periodSeconds), which cannot exceed 240 seconds, Cloud Run shuts down the container.If the HTTP startup probe succeeds within the specified time, and you have configured an HTTP liveness probe, Cloud Run starts the HTTP liveness probe. |
| HTTP liveness | Create anHTTP health check endpoint Use HTTP/1 | The liveness probe starts only after the startup probe is successful. After probe configuration, and any startup probe is successful, Cloud Run makes an HTTP GET request to the health check endpoint (for example,/health). Any response between200 and400 is a success, everything else indicates failure.If a liveness probe does not succeed within the specified time ( failureThreshold *periodSeconds), Cloud Run shuts down the container using aSIGKILL signal. Any remaining requests that were still being served by the container are terminated with the HTTP status code503. After Cloud Run shuts down the container, Cloud Run autoscaling starts up a new container instance. |
| gRPC startup | Implement thegRPC Health Checking protocol in your Cloud Run worker pool | If a startup probe does not succeed within the specified time (failureThreshold *periodSeconds), which cannot exceed 240 seconds, Cloud Run shuts down the container. |
| gRPC liveness | Implement thegRPC Health Checking protocol in your Cloud Run worker pool | If you configure a gRPC startup probe, the liveness probe starts only after the startup probe is successful. After the liveness probe is configured, and any startup probe is successful, Cloud Run makes a health check request to the worker pool. If a liveness probe does not succeed within the specified time ( failureThreshold *periodSeconds), Cloud Run shuts down the container using aSIGKILL signal. After Cloud Run shuts down the container, Cloud Run autoscaling starts up a new container instance. |
Configure probes
Any configuration change leads to thecreation of a new revision. Subsequent revisions will also automatically getthis configuration setting unless you make explicit updates to change it.
You can configure HTTP, TCP, and gRPC probes using the Google Cloud console orthe Cloud Run REST API:
Console
In the Google Cloud console, go to Cloud Run:
SelectWorker pools from the menu.
- If you are configuring a new worker pool, clickDeploy container.
- If you are configuring an existing worker pool, select theworker pool, then clickEdit and deploy new revision.
If you are configuring a new worker pool, fill out the initial workerpool page, then clickContainer(s), Volumes, Networking, Security to expand theworker pools configuration page.
In theContainer(s) section, go toHealth checks and clickAdd health check to open theAdd health check configurationpanel.
From theSelect health check type menu, select the type ofhealth check you want to add.
From theSelect probe type menu, select the type of the probeyou want to use, for example, HTTP or gRPC. This displays the probe configurationform.
Configure the probe settings, which vary by probe type:
If you are using HTTP probes:
Use thePath field to specify the relative path to theendpoint, for example,
/.Select theHTTP Headers checkbox to specify optional custom headers.Specify the header name in theName field and header value intheValue field. ClickAdd HTTP header to specify more headers.
If you are using gRPC probes, ensure that your container image implementsthe gRPC health check protocol. For more information, seeGRPC Health Checking Protocol.
For both HTTP and gRPC probe types, specify the following:
Initial delay, specify the number of seconds to wait after thecontainer has started before performing the first probe. Specify a value from 0 seconds to 240 seconds.The default value is 0 seconds.
Period, specify the period (in seconds) at which to perform theprobe. For example, specify
2to perform the probe every 2 seconds. Specify a valuefrom 1 second to 240 seconds. The default value is 10 seconds.Failure threshold, specify the number of times to retry the probebefore shutting down the container. The default value is 3.
Timeout, specify the number of seconds to wait until the probe timesout. Specify a value from 1 to the smaller of240 and
periodSeconds. The default is 1.
ClickAdd to add the new threshold.
ClickCreate orDeploy.
REST API
Important: If you are configuring your Cloud Run worker pool for HTTPprobes, you must alsoadd an HTTP health check endpoint in your worker poolcode to respond to the probe. If you are configuring a gRPC probe, you mustalso implement thegRPC Health Checking protocolin your Cloud Run worker pool.
Create HTTP health check endpoints
If you configure your Cloud Run worker pool for an HTTP startup probe orliveness probe, you need to add an endpoint in your worker pool code to respond tothe probe. The endpoint can have whatever name you want, for example,/startup or/ready, but the name must match the value you specify forpath in the probe configuration. For example, if you specify/ready for anHTTP startup probe, specifypath in your probe configuration as shown:
startupProbe:httpGet:path:/ready
HTTP health check endpoints are externally accessible and follow the sameprinciples as any other HTTP endpoints that are exposed externally.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.