You can configure HTTP, TCP, and gRPC startup health check probes, along with HTTP and gRPC liveness probes for new and existing Cloud Run services. You configure a startup or liveness probe for a Cloud Run service using the YAML file. The configuration varies depending on the type of probe.
You can use liveness check probes to determine when to restart a container, for example, to catch a deadlock where a service is running, but unable to make progress. Restarting a container in this case can increase service availability in the event of bugs.
You can use startup probes to determine when a container has started and is ready to accept traffic.
When you configure a startup probe, liveness checks are disabled until the startup probe determines that the container is started, to prevent interference with the service startup.
Startup probes are especially useful if you use liveness checks on slow starting containers, because it prevents them from being shut down prematurely before the containers are up and running.
Billing and CPU allocation
- CPU is allocated for every probe.
- All probes are billed for CPU and memory usage consumption, but there is no request-based charge.
Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.
Configure startup probes
You can configure HTTP, TCP, and gRPC probes.
Configure an HTTP startup probe
There are no default HTTP startup probes for HTTP, but you can configure one for your Cloud Run service. Note that using an HTTP health check probe requires you to create a corresponding HTTP healthcheck endpoint in your service to respond to the probe. Also, your service must use HTTP/1 (the Cloud Run default), not HTTP/2.
After the startup probe is configured, Cloud Run makes an HTTP GET
request to the service healthcheck endpoint (for example, /ready
). Any response between
200
and 400
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, the container is shut down.
If the HTTP startup probe succeeds within the specified time, and you have configured an HTTP liveness probe, the HTTP liveness probe is started.
You can configure an HTTP startup probe using Google Cloud console for an existing service, or YAML for a new or existing service:
Console
Click on the service you want to configure.
Click the YAML tab.
Click Edit and configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: httpGet: path: PATH port: CONTAINER_PORT httpHeaders: - name: HEADER_NAME value: HEADER_VALUE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- PATH with the relative path to the HTTP endpoint, for example,
/ready
. - (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- (OPTIONAL)
httpHeaders
can be used to supply multiple or repeated custom headers using the HEADER_NAME and HEADER_VALUE fields as shown. - (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 240. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe. For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Click Save and Deploy new Revision.
YAML
You can download and view existing service configurations using the
gcloud run services describe --format export
command, which yields
cleaned results in YAML format.
You can then modify the fields described below and
upload the modified YAML using the gcloud run services replace
command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloud run services describe SERVICE --format export > service.yaml
Configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: httpGet: path: PATH port: CONTAINER_PORT httpHeaders: - name: HEADER_NAME value: HEADER_VALUE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- PATH with the relative path to the HTTP endpoint, for example,
/ready
. - (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- (OPTIONAL)
httpHeaders
can be used to supply multiple or repeated custom headers using the HEADER_NAME and HEADER_VALUE fields as shown. - (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 240. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Replace the service with its new configuration using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Configure your Cloud Run service with startup_probe
attribute as shown:
Create HTTP healthcheck endpoints
If you configure your Cloud Run service for a HTTP startup probe or
liveness probe, you need to add an endpoint in your service code to respond to
the probe. The endpoint can have whatever name you want, for example,
/startup
or /ready
, but they must match the values you specify for
path
in the probe configuration. For example, if you specify /ready
for an
HTTP startup probe, you specify path
in your probe configuration as shown:
startupProbe: httpGet: path: /ready
HTTP Healthcheck endpoints are externally accessible and follow the same principles as any other HTTP service endpoints that are exposed externally.
Configure a TCP startup probe
A TCP startup probe is automatically configured with default values for a new Cloud Run service if you don't configure a startup probe yourself. The default probe is equivalent to the following:
startupProbe: tcpSocket: port: CONTAINER_PORT timeoutSeconds: 240 periodSeconds: 240 failureThreshold: 1
where CONTAINER_PORT is set to the container port used for your service.
You can change these default values following the instructions in this section.
For TCP startup probes, 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
(failureThreshold
* periodSeconds
), which cannot exceed
240 seconds, the container is shut down.
You can configure a TCP startup probe using Google Cloud console for an existing service, or YAML for a new or existing service:
Console
Click on the service you want to configure.
Click the YAML tab.
Click Edit and configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: failureThreshold: THRESHOLD initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT periodSeconds: PERIOD tcpSocket: port: CONTAINER_PORT
replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- (Optional) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 240. The default is 1. - (Optional) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (Optional) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Click Save and Deploy new Revision.
YAML
You can download and view existing service configurations using the
gcloud run services describe --format export
command, which yields
cleaned results in YAML format.
You can then modify the fields described below and
upload the modified YAML using the gcloud run services replace
command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloud run services describe SERVICE --format export > service.yaml
Configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: tcpSocket: port: CONTAINER_PORT initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 240. The default is 1. - THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Replace the service with its new configuration using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Configure your Cloud Run service with startup_probe
attribute as shown:
Configure a gRPC startup probe
To use a gRPC startup probe, you must implement the gRPC Health Checking protocol in your Cloud Run service, and then configure the probe accordingly, as described in this section.
You can configure a gRPC startup probe using Google Cloud console for an existing service, or YAML for a new or existing service:
Console
Click on the service you want to configure.
Click the YAML tab.
Click Edit and configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: grpc: service: GRPC_SERVICE port: CONTAINER_PORT initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- GRPC_SERVICE with the name of the gRPC service to send the health check to.
- (Optional) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 240. The default is 1. - (Optional) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (Optional) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Click Save and Deploy new Revision.
YAML
You can download and view existing service configurations using the
gcloud run services describe --format export
command, which yields
cleaned results in YAML format.
You can then modify the fields described below and
upload the modified YAML using the gcloud run services replace
command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloud run services describe SERVICE --format export > service.yaml
Configure the
startupProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL startupProbe: grpc: service: GRPC_SERVICE port: CONTAINER_PORT initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- GRPC_SERVICE with the name of the gRPC service to send the health check to.
- (OPTIONAL) CONTAINER_PORT should be set to the container port
used for your service.
- (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe times out. This value cannot exceed the value specified for periodSeconds. Specify a value from 1 to 240. The default is 1.
- (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to 240 seconds. The default value is 10 seconds.
Replace the service with its new configuration using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Configure your Cloud Run service with startup_probe
attribute as shown:
resource "google_cloud_run_service" "default" { provider = google-beta name = "cloudrun-service-healthcheck" location = "us-central1" project = "tf-healthchecks-grpc-probe-1" template { spec { containers { # Note: Change to the name of your image image = "us-docker.pkg.dev/cloudrun/container/hello" startup_probe { failure_threshold = 5 initial_delay_seconds = 10 timeout_seconds = 3 period_seconds = 3 grpc { # Note: Change to the name of your pre-existing grpc health status service service = "grpc.health.v1.Health" } } } } } traffic { percent = 100 latest_revision = true } }
Configure a liveness probe
You can configure HTTP and gRPC liveness probes.
Configure an HTTP liveness probe
If you configure an HTTP startup probe, the liveness probe starts only after the startup probe is successful. Note that using an HTTP health check probe requires you to create a corresponding HTTP healthcheck endpoint in your service to respond to the probe. Also, your service must use HTTP/1 (the Cloud Run default), not HTTP/2.
After the liveness probe is configured, and any startup probe is successful,
Cloud Run makes an HTTP GET
request to the service healthcheck endpoint (for example, /health
). Any response between
200
and 400
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, the container is shut down.
If the HTTP liveness probe fails within the specified time, the container is stopped and then will be restarted by the next incoming request.
You can configure an HTTP liveness probe using Google Cloud console for an existing service, or YAML for a new or existing service:
Console
Click on the service you want to configure.
Click the YAML tab.
Click Edit and configure the
livenessProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: image: IMAGE_URL livenessProbe: httpGet: path: PATH port: CONTAINER_PORT httpHeaders: - name: HEADER_NAME value: HEADER_VALUE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- PATH with the relative path to the HTTP endpoint, for example,
/ready
. - (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- (OPTIONAL)
httpHeaders
can be used to supply multiple or repeated custom headers using the HEADER_NAME and HEADER_VALUE fields as shown. - (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 3600. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to3600 seconds. The default value is 10 seconds.
Click Save and Deploy new Revision.
YAML
You can download and view existing service configurations using the
gcloud run services describe --format export
command, which yields
cleaned results in YAML format.
You can then modify the fields described below and
upload the modified YAML using the gcloud run services replace
command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloud run services describe SERVICE --format export > service.yaml
Configure the
livenessProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL livenessProbe: httpGet: path: PATH port: CONTAINER_PORT httpHeaders: - name: HEADER_NAME value: HEADER_VALUE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- PATH with the relative path to the HTTP endpoint, for example,
/ready
. - (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- (OPTIONAL)
httpHeaders
can be used to supply multiple or repeated custom headers using the HEADER_NAME and HEADER_VALUE fields as shown. - (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 3600. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to3600 seconds. The default value is 10 seconds.
Replace the service with its new configuration using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Configure your Cloud Run service with liveness_probe
attribute as shown:
After HTTP probe configuration, you must also create a healthcheck endpoint to respond to the probe.
Configure a gRPC liveness probe
If you configure a gRPC startup probe, the liveness probe starts only after the startup probe is successful. Note that using a gRPC health check probe requires you to implement the gRPC Health Checking protocol in your Cloud Run service.
After the liveness probe is configured, and any startup probe is successful, Cloud Run makes a health check request to the service.
If a startup probe does not succeed within the specified time
(failureThreshold
* periodSeconds
), which cannot exceed
240 seconds, the container is shut down.
If the gRPC liveness probe fails within the specified time, the container is stopped and then will be restarted by the next incoming request.
You can configure a gRPC liveness probe using Google Cloud console for an existing service, or YAML for a new or existing service:
Console
Click on the service you want to configure.
Click the YAML tab.
Click Edit and configure the
livenessProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: image: IMAGE_URL livenessProbe: grpc: port: CONTAINER_PORT service: GRPC_SERVICE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- GRPC_SERVICE with the name of the gRPC service to send the health check to.
- (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 3600. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe.
For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to3600 seconds. The default value is 10 seconds.
Click Save and Deploy new Revision.
YAML
You can download and view existing service configurations using the
gcloud run services describe --format export
command, which yields
cleaned results in YAML format.
You can then modify the fields described below and
upload the modified YAML using the gcloud run services replace
command.
Make sure you only modify fields as documented.
To view and download the configuration:
gcloud run services describe SERVICE --format export > service.yaml
Configure the
livenessProbe
attribute as shown:apiVersion: serving.knative.dev/v1 kind: Service metadata: name: SERVICE spec: template: metadata: spec: containers: - image: IMAGE_URL livenessProbe: grpc: port: CONTAINER_PORT service: GRPC_SERVICE initialDelaySeconds: DELAY timeoutSeconds: TIMEOUT failureThreshold: THRESHOLD periodSeconds: PERIOD
Replace
- SERVICE with the name of your Cloud Run service.
- IMAGE_URL with a reference to the container image, for
example,
us-docker.pkg.dev/cloudrun/container/hello:latest
- (OPTIONAL) CONTAINER_PORT should be set to the container port used for your service.
- GRPC_SERVICE with the name of the gRPC service to send the health check to.
- (OPTIONAL) DELAY with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 240 seconds. The default value is 0 seconds.
- (OPTIONAL) TIMEOUT with the number of seconds to wait until the probe
times out. This value cannot exceed the value specified for
periodSeconds
. Specify a value from 1 to 3600. The default is 1. - (OPTIONAL) THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
- (OPTIONAL) PERIOD with the period (in seconds) at which to perform the probe. For example
2
to perform the probe every 2 seconds. Specify a value from 1 second to3600 seconds. The default value is 10 seconds.
Replace the service with its new configuration using the following command:
gcloud run services replace service.yaml
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Configure your Cloud Run service with liveness_probe
attribute as shown: