Startup probes let you verify that a container has successfully initialized
before running workloads in Cloud Run jobs. You can configure HTTP,
TCP, or gRPC probes for both new and existing jobs to detect startup failures
early.

## Use cases

You can configure startup health check probes to determine whether
the container has started and is ready to execute the job.

When a job repeatedly fails to start, Cloud Run limits task restarts to
prevent uncontrolled crash loops.

## Probe requirements and behavior

| Probe Type | Requirements | Behavior |
|---|---|---|
| TCP startup | None | If Cloud Run can't establish a connection, it indicates a failure. If a startup probe does not succeed within the specified time interval, Cloud Run shuts down the container. This time interval is calculated as `failureThreshold` \* `periodSeconds` and can't exceed 600 seconds (1800 for GPU). |
| HTTP startup | Create an [HTTP health check endpoint](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks.md.txt#healthcheck-endpoint) Use HTTP/1 | After you configure the probe, Cloud Run makes an HTTP GET request to the job health check 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 600 seconds (1800 for GPU), the container is shut down |
| gRPC startup | Implement the [gRPC Health Checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md) in your Cloud Run job | If a startup probe does not succeed within the specified time (`failureThreshold` \* `periodSeconds`), which cannot exceed 600 seconds (1800 for GPU), the container is shut down |

## Configure probes

Configure HTTP, TCP, and gRPC probes using the Google Cloud console or YAML:

### Console


Important: If you are configuring your Cloud Run job for HTTP
probes, you must also [add an HTTP health check endpoint](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks.md.txt#healthcheck-endpoint) in your job code to respond to the probe. If you are configuring a gRPC probe, you must also implement the [gRPC Health Checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)
in your Cloud Run job.

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

   [Go to Cloud Run](https://console.cloud.google.com/run/jobs)
2. For a new job, click **Deploy container** . For an existing job, click the **Jobs** tab, click the job you want, then click **View and edit job configuration**.

3. Expand **Containers, Networking, Security**.

4. In the **Container(s)** section, go to **Health checks** and click
   **Add health check** to open the **Add health check** configuration
   panel.

5. From the **Select health check type** menu, select the health check
   startup type.

6. From the **Select probe type** menu, select the type of the probe, such as
   HTTP or gRPC. This displays the probe configuration
   form.

7. Note that probe configuration varies by probe type. Configure the probe settings:

   - If you are using HTTP probes:
     - Use the **Path** field to specify the relative path to the [endpoint](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks.md.txt#healthcheck-endpoint), for example, `/`.
     - Select the **HTTP Headers** checkbox to specify optional custom headers. Then specify the header name in the **Name** field and header value in the **Value** field. Click **Add HTTP header** to specify more headers.
   - For **Port**, specify the port where the job container listens for the probe.
   - For **Initial delay**, specify how many seconds to wait after the container starts before performing the first probe. Specify a value from 0 seconds to 600 seconds (1800 for GPU). The default value is 0 seconds.
   - For **Period** , specify the time interval (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 600 seconds (1800 for GPU). The default value is 10 seconds.
   - For **Failure threshold**, specify how many times to retry the probe before shutting down the container. The default value is 3.
   - For **Timeout** , specify how many seconds to wait until the probe times out. *This value cannot exceed the value specified for `periodSeconds`.* Specify a value from 1 to 600 (1800 for GPU). The default is 1.
8. Click **Add** to add the new threshold

### YAML


Important: If you are configuring your Cloud Run job for HTTP
probes, you must also [add an endpoint](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks.md.txt#healthcheck-endpoint) in your job
code to respond to the probe. If you are configuring a gRPC probe, you must
also implement the
[gRPC Health Checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)
in your Cloud Run job.

### TCP startup

1. If you are creating a new job, skip this step. If you are updating an existing job, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt#job):

   ```bash
   gcloud run jobs describe JOB_NAME --format export > job.yaml
   ```
2. Configure the `startupProbe` attribute as shown:

   ```yaml
   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
    name: JOB
   spec:
    template:
      metadata:
      spec:
        containers:
        - image: IMAGE_URL
          startupProbe:
            tcpSocket:
              port: CONTAINER_PORT
            initialDelaySeconds: DELAY
            timeoutSeconds: TIMEOUT
            failureThreshold: THRESHOLD
            periodSeconds: PERIOD
   ```

   Replace the following variables:
   - <var translate="no">JOB</var> with the name of your Cloud Run job.
   - <var translate="no">IMAGE_URL</var> with the URL of the job container image, for example, `us-docker.pkg.dev/cloudrun/container/job:latest`.
   - Optional: <var translate="no">CONTAINER_PORT</var> with the port where the job container listens for the probe.
   - <var translate="no">DELAY</var> with the number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 600 seconds (1800 for GPU). The default value is 0 seconds.
   - Optional: <var translate="no">TIMEOUT</var> 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 600 (1800 for GPU). The default is 1.
   - <var translate="no">THRESHOLD</var> with the number of times to retry the probe before shutting down the container. The default value is 3.
   - <var translate="no">PERIOD</var> 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 600 seconds (1800 for GPU). The default value is 10 seconds.
3. Create or update the job using the following command:

   ```bash
   gcloud run jobs replace job.yaml
   ```

### HTTP startup

1. If you are creating a new job, skip this step. If you are updating an existing job, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt#job):

   ```bash
   gcloud run jobs describe JOB_NAME --format export > job.yaml
   ```
2. Configure the `startupProbe` attribute as shown:

   ```yaml
   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB
   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 the following variables:
   - <var translate="no">JOB</var> with the name of your Cloud Run job.
   - <var translate="no">IMAGE_URL</var> with the URL of the job container image, for example, `us-docker.pkg.dev/cloudrun/container/job:latest`.
   - <var translate="no">PATH</var> with the relative path to the [HTTP endpoint](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks.md.txt#healthcheck-endpoint), for example, `/ready`.
   - Optional: <var translate="no">CONTAINER_PORT</var> with the port where the job container listens for the probe.
   - Optional: `httpHeaders` can be used to supply multiple or repeated custom headers using the <var translate="no">HEADER_NAME</var> and <var translate="no">HEADER_VALUE</var> fields as shown.
   - Optional: <var translate="no">DELAY</var> with number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 600 seconds (1800 for GPU). The default value is 0 seconds.
   - Optional: <var translate="no">TIMEOUT</var> 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 600 (1800 for GPU). The default is 1.
   - Optional: <var translate="no">THRESHOLD</var> with the number of times to retry the probe before shutting down the container. The default value is 3.
   - Optional: <var translate="no">PERIOD</var> 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 600 seconds (1800 for GPU). The default value is 10 seconds.
3. Create or update the job using the following command:

   ```bash
   gcloud run jobs replace job.yaml
   ```

### gRPC startup

1. If you are creating a new job, skip this step. If you are updating an existing job, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt#job):

   ```bash
   gcloud run jobs describe JOB_NAME --format export > job.yaml
   ```
2. Configure the `startupProbe` attribute as shown:

   ```yaml
   apiVersion: run.googleapis.com/v1
   kind: Job
   metadata:
     name: JOB
   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 the following variables:
   - <var translate="no">JOB</var> with the name of your Cloud Run job.
   - <var translate="no">IMAGE_URL</var> with the URL of the job container image, for example, `us-docker.pkg.dev/cloudrun/container/job:latest`.
   - Optional: <var translate="no">GRPC_SERVICE</var>. If set, this is used in the service field of the `grpc.health.v1.HealthCheckRequest` when the `grpc.health.v1.Health.Check` RPC is called.
   - Optional: <var translate="no">CONTAINER_PORT</var> with the port where the job container listens for the probe.
   - Optional: <var translate="no">DELAY</var> with the number of seconds to wait after the container has started before performing the first probe. Specify a value from 0 seconds to 600 seconds (1800 for GPU). 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 600 (1800 for GPU). The default is 1.
   - Optional: <var translate="no">THRESHOLD</var> with the number of times to retry the probe before shutting down the container. The default value is 3.
   - Optional: <var translate="no">PERIOD</var> 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 600 seconds (1800 for GPU). The default value is 10 seconds.
3. Create or update the job using the following command:

   ```bash
   gcloud run jobs replace job.yaml
   ```

## Create HTTP health check endpoints

If you configure your Cloud Run job for an HTTP startup probe, you
must add an endpoint in your job code to respond to the probe. You can use any
name for the endpoint, such as, `/startup` or `/ready`. The name must match the
values you specify for `path` in the probe configuration. For example, if you
specify `/ready` for an HTTP startup probe, specify `path` in your probe
configuration as shown:

<br />

```bash
startupProbe:
  httpGet:
    path: /ready
```

<br />