Configure container health checks for services

Cloud Run health checks ensure that your container instances are runningcorrectly and are able to serve traffic. With Cloud Run health checks,you can customize when your container is ready to receive requests, andwhen your container should be considered unhealthy to require a restart.

Use cases

You can configure the following types of health check probes:

  • Startup probes determine whether the container hasstarted and is ready to accept traffic.

    • When you configure a startup probe, liveness and readiness checks are disabled untilthe startup probe determines that the container is started, to preventinterference with the service startup.
    • Startup probes are especially useful if you use liveness checks on slowstarting containers, because startup probes prevents the containers frombeing shut down prematurely before the containers are up and running.

  • Liveness probes determine whether to restart acontainer.

    • Restarting a container in this case can increase service availability inthe event of bugs.
    • Liveness probes are intended to restart individual instances that can'tbe recovered in any other way. They should be used primarily forunrecoverable instance failures, such as catching a deadlock where aservice is running, but is unable to make progress. You can require aliveness probe for every container by usingcustom organizationpolicies.
    • When a service experiences repeated probe failures, Cloud Runlimits instance restarts to prevent uncontrolled crash loops.

  • Readiness probes (Preview)

    Readiness probes determine when an instance in your Cloud Runservice should serve traffic. The readiness checks begin after thecontainer's startup probe successfully passes. If an instance fails itsreadiness probe beyond the failure threshold value you configure,Cloud Run stops sending new traffic to it. Cloud Run doesn'tterminate the instance and sends traffic back tothe instance when it starts passing its readiness probe again.

Your container should implement the startup, liveness, and readinessprobes consistently. Once the startup check passes, Cloud Run considersyour container ready to serve traffic.

Configure startup 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 Google Cloud console, YAML, orTerraform:

Console

  1. In the Google Cloud console, go to theCloud Run page:

    Go to Cloud Run

  2. For a new service, expandContainer(s), Volumes, Networking, Security to display the health checkoptions. For an existing service, click the service you want to configure,then clickEdit and deploy to display the health check options.

  3. In theContainer(s) section, go toHealth checks and clickAdd health check to open theAdd health check configurationpanel.

  4. From theSelect health check type menu, selectStartup check.

  5. From theSelect probe type menu, select the type of the probeyou want to use, for example, HTTP or gRPC. This displays the probe configurationform.

  6. Probe configuration varies by probe type. Configure the probe settings:

    • If you are using HTTP probes:

      • Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

      • Use thePath field to specify the relative path to the endpoint, 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:

    • ForPort, specify thecontainer port used for your service.

    • ForInitial 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.

    • ForPeriod, specify the period (in seconds) at which to perform theprobe. For example2 to perform the probe every 2 seconds. Specify a valuefrom 1 second to 240 seconds. The default value is 10 seconds.

    • ForFailure threshold, specify the number of times to retry the probebefore shutting down the container. The default value is 3.

    • ForTimeout, specify the number of seconds to wait until the probe timesout. This value cannot exceed the value specified forperiodSeconds. Specifya value from 1 to 240. The default is 1.

  7. ClickAdd to add the new threshold.

  8. ClickCreate orDeploy.

To delete a probe, click theDelete icon for the health check you want to delete, then clickDeploy to deploy a new revision of your Cloud Run service.

gcloud

TCP startup

Run the following command:

  gcloud run deploySERVICE \      --image=IMAGE_URL \      --startup-probe tcpSocket.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • Optional.CONTAINER_PORT: thecontainer portused for your service.
  • DELAY: number of seconds to wait after the containerhas started before performing the first probe. Specify a value from 0 seconds to 240 seconds.The default value is 0 seconds.
  • Optional.TIMEOUT: the number of seconds to wait until the probetimes out. This value cannot exceed the value specified forperiodSeconds.Specify a value from 1 to 240.The default is 1.
  • THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
  • PERIOD: period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds.The default value is 10 seconds.

HTTP startup

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

Run the following command:

  gcloud run deploySERVICE \      --image=IMAGE_URL \      --startup-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • PATH: a relative path to the HTTP endpoint, for example,/health.
  • Optional.CONTAINER_PORT: set to thecontainer port used for your service.
  • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
  • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
  • Optional.TIMEOUT: the number of seconds to waituntil the probe times out. This value cannot exceed the value specifiedfor periodSeconds. Specify a value from 1to 240. The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds. The default value is 10 seconds.

gRPC startup

Ensure that your container image implementsthegRPC health check protocol.

Run the following command:

  gcloud run deploySERVICE \      --image=IMAGE_URL \      --startup-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
  • Optional.CONTAINER_PORT: thecontainer port used for your service.
  • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
  • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
  • Optional.TIMEOUT: the number of seconds to waituntil the probe times out. This value cannot exceed the value specifiedfor periodSeconds. Specify a value from 1to 240. The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds. The default value is 10 seconds.

YAML

TCP startup

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thestartupProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEspec:template:metadata:spec:containers:-image:IMAGE_URLstartupProbe:tcpSocket:port:CONTAINER_PORTinitialDelaySeconds:DELAYtimeoutSeconds:TIMEOUTfailureThreshold:THRESHOLDperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • Optional.CONTAINER_PORT: thecontainer portused for your service.
    • DELAY: number of seconds to wait after the containerhas started before performing the first probe. Specify a value from 0 seconds to 240 seconds.The default value is 0 seconds.
    • Optional.TIMEOUT: the number of seconds to wait until the probetimes out. This value cannot exceed the value specified forperiodSeconds.Specify a value from 1 to 240.The default is 1.
    • THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
    • PERIOD: period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds.The default value is 10 seconds.
  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

HTTP startup

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thestartupProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEspec:template:metadata:spec:containers:-image:IMAGE_URLstartupProbe:httpGet:path:PATHport:CONTAINER_PORThttpHeaders:-name:HEADER_NAMEvalue:HEADER_VALUEinitialDelaySeconds:DELAYtimeoutSeconds:TIMEOUTfailureThreshold:THRESHOLDperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • PATH: a relative path to the HTTP endpoint, for example,/health.
    • Optional.CONTAINER_PORT: set to thecontainer port used for your service.
    • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
    • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
    • Optional:httpHeaders can be used to supplymultiple or repeated custom headers using theHEADER_NAME andHEADER_VALUE fields as shown.
    • Optional.TIMEOUT: the number of seconds to waituntil the probe times out. This value cannot exceed the value specifiedfor periodSeconds. Specify a value from 1to 240. The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds. The default value is 10 seconds.
  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

gRPC startup

Ensure that your container image implementsthegRPC health check protocol.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thestartupProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEspec:template:metadata:spec:containers:-image:IMAGE_URLstartupProbe:grpc:service:GRPC_SERVICEport:CONTAINER_PORTinitialDelaySeconds:DELAYtimeoutSeconds:TIMEOUTfailureThreshold:THRESHOLDperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
    • Optional.CONTAINER_PORT: thecontainer port used for your service.
    • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
    • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
    • Optional.TIMEOUT: the number of seconds to waituntil the probe times out. This value cannot exceed the value specifiedfor periodSeconds. Specify a value from 1to 240. The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probe every 2 seconds. Specify avalue from 1 second to 240 seconds. The default value is 10 seconds.
  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

Terraform

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

TCP startup

Configure your Cloud Run service withstartup_probe attribute as shown:

resource"google_cloud_run_v2_service""default"{name="cloudrun-service-healthcheck"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{image="us-docker.pkg.dev/cloudrun/container/hello"startup_probe{failure_threshold=5initial_delay_seconds=10timeout_seconds=3period_seconds=3tcp_socket{port=8080}}}}}

HTTP startup

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

Configure your Cloud Run service withstartup_probe attribute as shown:

resource"google_cloud_run_v2_service""default"{name="cloudrun-service-healthcheck"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{image="us-docker.pkg.dev/cloudrun/container/hello"startup_probe{failure_threshold=5initial_delay_seconds=10timeout_seconds=3period_seconds=3http_get{path="/"          # Custom headers to set in the request          # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#http_headershttp_headers{name="Access-Control-Allow-Origin"value="*"}}}}}}

gRPC startup

Ensure that your container image implementsthegRPC health check protocol.

Configure your Cloud Run service withstartup_probe attribute as shown:

resource"google_cloud_run_v2_service""default"{name="cloudrun-service-healthcheck"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{      # Note: Change to the name of your imageimage="us-docker.pkg.dev/cloudrun/container/hello"startup_probe{failure_threshold=5initial_delay_seconds=10timeout_seconds=3period_seconds=3grpc{          # Note: Change to the name of your pre-existing grpc health status serviceservice="grpc.health.v1.Health"}}}}}

The default TCP startup probe

If you don't explicitly configure a TCP startup probe for a newCloud Run service, Cloud Run automatically configures aTCP startup probe with the following default values:

startupProbe:timeoutSeconds:240periodSeconds:240failureThreshold:1

You can change these default values following the instructions in theprobe configuration section on this page.

Startup probe requirements and behavior

Probe TypeRequirementsBehavior
TCP startupNoneBy default, 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. See alsoTCP defaults.
HTTP startupCreate an HTTP health check endpoint
Use HTTP/1		After probe configuration, Cloud Run makes an HTTP GET request to the health check endpoint (for example,/health). Any2XX or3XX response 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.
gRPC startupImplement thegRPC Health Checking protocol in your Cloud Run serviceIf a startup probe does not succeed within the specified time (failureThreshold *periodSeconds), which cannot exceed 240 seconds, the container is shut down.

Configure liveness 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 and gRPC probes using Google Cloud console, YAML, or Terraform:

Console

  1. In the Google Cloud console, go to theCloud Run page:

    Go to Cloud Run

  2. For a new service, expandContainer(s), Volumes, Networking, Security to display the health checkoptions. For an existing service, click the service you want to configure,then clickEdit and deploy to display the health check options.

  3. In theContainer(s) section, go toHealth checks and clickAdd health check to open theAdd health check configurationpanel.

  4. From theSelect health check type menu, selectLiveness check.

  5. From theSelect probe type menu, select the type of the probeyou want to use, for example, HTTP or gRPC. This displays the probe configurationform.

  6. Probe configuration varies by probe type. Configure the probe settings:

    • If you are using HTTP probes:

      • Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

      • Use thePath field to specify the relative path to the endpoint, 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:

    • ForPort, specify thecontainer port used for your service.

    • ForInitial 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.

    • ForPeriod, specify the period (in seconds) at which to perform theprobe. For example2 to perform the probe every 2 seconds. Specify a valuefrom 1 second to 3600 seconds. The default value is 10 seconds.

    • ForFailure threshold, specify the number of times to retry the probebefore shutting down the container. The default value is 3.

    • ForTimeout, specify the number of seconds to wait until the probe timesout. This value cannot exceed the value specified forperiodSeconds. Specifya value from 1 to 3600. The default is 1.

  7. ClickAdd to add the new threshold.

  8. ClickCreate orDeploy.

To delete a probe, click theDelete icon for the health check you want to delete, then clickDeploy to deploy a new revision of your Cloud Run service.

gcloud

HTTP liveness

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

Run the following command:

  gcloud run deploySERVICE \      --image=IMAGE_URL \      --liveness-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • PATH: a relative path to the HTTP endpoint, for example,/health.
  • Optional.CONTAINER_PORT: set to thecontainer port used for your service.
  • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
  • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
  • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 3600.The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probeevery 2 seconds. Specify a value from 1 second to 3600 seconds. The default value is 10 seconds.

gRPC liveness

Ensure that your container image implementsthegRPC health check protocol.

Run the following command:

  gcloud run deploySERVICE \      --image=IMAGE_URL \      --liveness-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
  • Optional.CONTAINER_PORT: thecontainer port used for your service.
  • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
  • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
  • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 3600.The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probeevery 2 seconds. Specify a value from 1 second to 3600 seconds. The default value is 10 seconds.

YAML

HTTP liveness

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thelivenessProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEspec:template:metadata:spec:containers:-image:IMAGE_URLlivenessProbe:httpGet:path:PATHport:CONTAINER_PORThttpHeaders:-name:HEADER_NAMEvalue:HEADER_VALUEinitialDelaySeconds:DELAYtimeoutSeconds:TIMEOUTfailureThreshold:THRESHOLDperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • PATH: a relative path to the HTTP endpoint, for example,/health.
    • Optional.CONTAINER_PORT: set to thecontainer port used for your service.
    • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
    • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
    • Optional:httpHeaders can be used to supplymultiple or repeated custom headers using theHEADER_NAME andHEADER_VALUE fields as shown.
    • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 3600.The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probeevery 2 seconds. Specify a value from 1 second to 3600 seconds. The default value is 10 seconds.
  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

gRPC liveness

Ensure that your container image implementsthegRPC health check protocol.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thelivenessProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEspec:template:metadata:spec:containers:-image:IMAGE_URLlivenessProbe:grpc:port:CONTAINER_PORTservice:GRPC_SERVICEinitialDelaySeconds:DELAYtimeoutSeconds:TIMEOUTfailureThreshold:THRESHOLDperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repositoryREPO_NAME must already be created. The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
    • Optional.CONTAINER_PORT: thecontainer port used for your service.
    • Optional.DELAY: the number of seconds to wait after the containerhas started before performing the first probe. Specify avalue from 0 seconds to 240 seconds.The default value is 0 seconds.
    • Optional.THRESHOLD: the number of times to retry the probe beforeshutting down the container. The default value is 3.
    • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 3600.The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe. For example2 to perform the probeevery 2 seconds. Specify a value from 1 second to 3600 seconds. The default value is 10 seconds.

  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

Terraform

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

HTTP liveness

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

Configure your Cloud Run service withliveness_probe attribute as shown:

resource"google_cloud_run_v2_service""default"{name="cloudrun-service-healthcheck"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{image="us-docker.pkg.dev/cloudrun/container/hello"liveness_probe{failure_threshold=5initial_delay_seconds=10timeout_seconds=3period_seconds=3http_get{path="/"          # Custom headers to set in the request          # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#http_headershttp_headers{name="Access-Control-Allow-Origin"value="*"}}}}}}

gRPC liveness

Ensure that your container image implementsthegRPC health check protocol.

Configure your Cloud Run service withliveness_probe attribute as shown:

resource"google_cloud_run_v2_service""default"{name="cloudrun-service-healthcheck"location="us-central1"deletion_protection=false # set to "true" in productiontemplate{containers{      # Note: Change to the name of your imageimage="us-docker.pkg.dev/cloudrun/container/hello"liveness_probe{failure_threshold=5initial_delay_seconds=10timeout_seconds=3period_seconds=3        # Note: Change to the name of your pre-existing grpc health status servicegrpc{service="grpc.health.v1.Health"}}}}}

Liveness probe requirements and behavior

Probe TypeRequirementsBehavior
HTTP livenessCreate an HTTP 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). Any2XX or3XX response is a success, everything else indicates failure.

If a liveness probe does not succeed within the specified time (failureThreshold *periodSeconds), the container is shut down using aSIGKILL signal. Any remaining requests that were still being served by the container are terminated with the HTTP status code503. After the container is shut down, Cloud Run autoscaling starts up a new container instance.
gRPC livenessImplement thegRPC Health Checking protocol in your Cloud Run serviceIf 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 service.

If a liveness probe does not succeed within the specified time (failureThreshold *periodSeconds), the container is shut down using aSIGKILL signal. After the container is shut down, Cloud Run autoscaling starts up a new container instance.

Configure readiness 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.

Preview — Readiness probes

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.

The following limitations apply to readiness probes:

  • If you enable session affinity, Cloud Run continues to sendrequests to the same instance, even if its readiness check fails.

  • If you previously configured a readiness probe for your Cloud Runservice using the Cloud Run Admin API v1 before November 2025, your readinesschecks won't take effect even after you deploy a new configuration for thatservice. This occurs because the service retains an older configuration.Services you create after November 2025, or those that never used a readinessprobe, are unaffected. To enable supported readiness probes on affectedservices, do the following:

    1. Deploy a new revision that removes the older readiness probe definition.

    2. Deploy another new revision that adds the relevant readiness probedefinition.

    These steps clear any older configuration and enable the readiness probefunctionality.

You can configure a readiness probe using the Google Cloud console, the Google Cloud CLIor YAML:

Console

  1. In the Google Cloud console, go to theCloud Run page:

    Go to Cloud Run

  2. For a new service, expandContainer(s), Volumes, Networking, Security to display the health checkoptions. For an existing service, click the service you want to configure,then clickEdit and deploy to display the health check options.

  3. In theContainer(s) section, go toHealth checks and clickAdd health check to open theAdd health check configurationpanel.

  4. From theSelect health check type menu, selectReadiness check.

  5. From theSelect probe type menu, select the type of the probeyou want to use, for example, HTTP or gRPC. This displays the probe configurationform.

  6. Probe configuration varies by probe type. Configure the probe settings:

    • If you are using HTTP probes:

      • Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

      • Use thePath field to specify the relative path to the endpoint,for example,/are_you_ready. The default path is/.

    • If you are using gRPC probes:

    • ForPort, specify the container port for your service. The defaultport is the main ingress port.

    • ForPeriod, specify the period (in seconds) at which to performthe probe. For example2 to perform the probe every 2 seconds.Specify a value from 1 to 300. The default value is 10 seconds.

    • ForSuccess threshold, specify the minimum consecutive successesfor the probe to be considered successful after failure. The defaultis 2.

    • ForFailure threshold, specify the number of times to retry theprobe before reporting a failure, which causes the instance to stopreceiving traffic. The default value is3.

    • ForTimeout, specify the number of seconds to wait until theprobe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from1 to 300. The default is 1.

  7. ClickAdd to add the new threshold.

  8. ClickCreate orDeploy.

To delete a probe, click theDelete icon for the health check you want to delete, then clickDeploy to deploy a new revision of your Cloud Run service.

gcloud

HTTP readiness

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

Run the following command:

gcloud beta run deploySERVICE \    --image=IMAGE_URL \    --readiness-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,successThreshold=SUCCESS_THRESHOLD,failureThreshold=FAILURE_THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you useArtifact Registry, the repositoryREPO_NAME must already be created.The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • Optional.PATH: the relative path to the HTTP endpoint, for example,/are_you_ready. The default path is/.
  • Optional.CONTAINER_PORT: the container port used for your service. The default portis the main ingress port.
  • Optional.SUCCESS_THRESHOLD: the minimum consecutivesuccesses for the probe to be considered successful after failure. The default is 2.
  • Optional.FAILURE_THRESHOLD: the number of times to retry theprobe before reporting a failure, which causes the instance to stop receiving traffic. The default is 3.
  • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 300. The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 to 300. The default value is 10 seconds.

gRPC readiness

Ensure that your container image implementsthegRPC health check protocol.

Run the following command:

gcloud beta run deploySERVICE \    --image=IMAGE_URL \    --readiness-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,successThreshold=SUCCESS_THRESHOLD,failureThreshold=FAILURE_THRESHOLD,timeoutSeconds=TIMEOUT,periodSeconds=PERIOD

Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you useArtifact Registry, the repositoryREPO_NAME must already be created.The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
  • Optional.CONTAINER_PORT: the container port used for your service. The default port is the main ingress port.
  • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
  • Optional.SUCCESS_THRESHOLD: the minimum consecutivesuccesses for the probe to be considered successful after failure. The default is 2.
  • Optional.FAILURE_THRESHOLD: the number of times to retry theprobe before reporting a failure, which causes the instance to stop receiving traffic. The default is 3.
  • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 300. The default is 1.
  • Optional.PERIOD: the period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 to 300. The default value is 10 seconds.

YAML

HTTP readiness

Add an HTTP/1 endpoint (the Cloud Run default, not HTTP/2) in yourservice code to respond to the probe. The endpoint name (for example,/startup,/health or/are_you_ready) must match thepath inthe probe configuration. HTTP health check endpoints are externally accessibleand follow the same principles as any other externally exposed HTTP service endpoints.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thereadinessProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEannotations:run.googleapis.com/launch-stage:BETAspec:template:metadata:spec:containers:-image:IMAGE_URLreadinessProbe:httpGet:path:PATHport:CONTAINER_PORTsuccessThreshold:SUCCESS_THRESHOLDfailureThreshold:FAILURE_THRESHOLDtimeoutSeconds:TIMEOUTperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you useArtifact Registry, the repositoryREPO_NAME must already be created.The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • Optional.PATH: the relative path to the HTTP endpoint, for example,/are_you_ready. The default path is/.
    • Optional.CONTAINER_PORT: the container port used for your service. The default portis the main ingress port.
    • Optional.SUCCESS_THRESHOLD: the minimum consecutivesuccesses for the probe to be considered successful after failure. The default is 2.
    • Optional.FAILURE_THRESHOLD: the number of times to retry theprobe before reporting a failure, which causes the instance to stop receiving traffic. The default is 3.
    • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 300. The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 to 300. The default value is 10 seconds.

  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

gRPC readiness

Ensure that your container image implementsthegRPC health check protocol.

  1. If you are creating a new service, skip this step. If you are updating an existing service, downloaditsYAML configuration:
    gcloudrunservicesdescribeSERVICE--formatexport>service.yaml

  2. Configure thereadinessProbe attribute as shown:

    apiVersion:serving.knative.dev/v1kind:Servicemetadata:name:SERVICEannotations:run.googleapis.com/launch-stage:BETAspec:template:metadata:spec:containers:-image:IMAGE_URLreadinessProbe:grpc:port:CONTAINER_PORTservice:GRPC_SERVICEsuccessThreshold:SUCCESS_THRESHOLDfailureThreshold:FAILURE_THRESHOLDtimeoutSeconds:TIMEOUTperiodSeconds:PERIOD

    Replace the following:

    • SERVICE: the name of your Cloud Run service.
    • IMAGE_URL: a reference to the container image, for example,us-docker.pkg.dev/cloudrun/container/hello:latest. If you useArtifact Registry, the repositoryREPO_NAME must already be created.The URL has the shapeLOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG.
    • Optional.CONTAINER_PORT: the container port used for your service. The default port is the main ingress port.
    • Optional.GRPC_SERVICE: If set, this is used in theservice field of thegrpc.health.v1.HealthCheckRequest when thegrpc.health.v1.Health.Check rpc is called.
    • Optional.SUCCESS_THRESHOLD: the minimum consecutivesuccesses for the probe to be considered successful after failure. The default is 2.
    • Optional.FAILURE_THRESHOLD: the number of times to retry theprobe before reporting a failure, which causes the instance to stop receiving traffic. The default is 3.
    • Optional.TIMEOUT: the number of seconds towait until the probe times out. This value cannot exceed the value specified forperiodSeconds. Specify a value from 1 to 300. The default is 1.
    • Optional.PERIOD: the period (in seconds) at which to perform the probe.For example2 to perform the probe every 2 seconds. Specify avalue from 1 to 300. The default value is 10 seconds.

  3. Create or update the service using the following command:
    gcloudrunservicesreplaceservice.yaml

CPU allocation

  • CPU is always allocated when probes run.
  • All probes are billed for CPU and memory usage consumption, but there is no request-based charge.

What's next

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.