Container health checks (services)

Stay organized with collections Save and categorize content based on your preferences.

You can configure HTTP and TCP startup health check probes, along with HTTP liveness probes for new and existing Cloud Run services.

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.

Configure startup probes

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.

You can configure the following types of probes:

  • HTTP startup probe
  • TCP startup probe
  • HTTP liveness probe

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.

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.

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

  1. Go to Cloud Run

  2. Click on the service you want to configure.

  3. Click the YAML tab.

  4. 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
            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) 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 frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  5. Click Save and Deploy new Revision.

YAML

You can download and view existing service configuration 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.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. 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
                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) 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 frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

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 port is already set to the container port, and will remain set to the container port even if you attempt to set it when you update the probe configuration.

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

  1. Go to Cloud Run

  2. Click on the service you want to configure.

  3. Click the YAML tab.

  4. 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:
            tcpSocket:
              port: CONTAINER_PORT
            initialDelaySeconds: DELAY
            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
    • CONTAINER_PORT is already set to whatever the container port is. It will remain set to the container port even if you attempt to set it when you update the probe.
    • 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.
    • THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
    • PERIOD with the frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  5. Click Save and Deploy new Revision.

YAML

You can download and view existing service configuration 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.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. 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
              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
    • CONTAINER_PORT is already set to whatever the container port is; this value should not be changed.
    • 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.
    • THRESHOLD with the number of times to retry the probe before marking the container as Unready. The default value is 3.
    • PERIOD with the frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

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.

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

  1. Go to Cloud Run

  2. Click on the service you want to configure.

  3. Click the YAML tab.

  4. 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
            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) 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 frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  5. Click Save and Deploy new Revision.

YAML

You can download and view existing service configuration 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.

  1. To view and download the configuration:

    gcloud run services describe SERVICE --format export > service.yaml
  2. 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
                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) 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 frequency (in seconds) to perform the probe. Specify a value from 1 second to240 seconds. The default value is 10 seconds.
  3. Replace the service with its new configuration using the following command:

    gcloud run services replace service.yaml

After HTTP probe configuration, you must also create a healthcheck endpoint to respond to the probe.