配置容器健康检查（服务）

您可以为新的和现有的 Cloud Run 服务配置 HTTP、TCP 和 gRPC 启动探测以及 HTTP 和 gRPC 活跃性探测。具体配置会因探测类型而异。

请注意，系统会自动为新的 Cloud Run 服务配置 TCP 启动探测。如需了解详情，请参阅默认 TCP 启动探测。

使用场景

您可以配置两种类型的健康检查探测：

  • 活跃性探测确定是否重启容器。

    • 在这种情况下，重启容器可以在出现错误时提高服务可用性。
    • 重要提示：活跃性探测旨在重启无法以任何其他方式恢复的单个实例。它们主要应该用于不可恢复的实例故障，例如，捕获服务正在运行但无进展的死锁。您可以使用自定义组织政策，要求每个容器都进行活跃性探测。

  • 启动探测确定容器是否已启动并已准备好接受流量。

    • 配置启动探测时，系统将停用活跃性检查，直到启动探测确定容器已启动，以防止干扰服务启动。
    • 如果您对慢启动容器使用活跃检查，则启动探测特别有用，因为它可以防止在容器启动和运行之前过早关停。

请注意，当服务重复发生启动或活跃性探测失败时，Cloud Run 会限制实例重启，以防止不受控制的崩溃循环。

默认 TCP 启动探测

系统会自动为具有默认值的新 Cloud Run 服务配置 TCP 启动探测。默认探测如下所示：

startupProbe:
  tcpSocket:
    port: CONTAINER_PORT
  timeoutSeconds: 240
  periodSeconds: 240
  failureThreshold: 1

将 CONTAINER_PORT 替换为为您的服务设置的容器端口。

您可以按照本页面的探测配置部分中的说明更改这些默认值。

结算和 CPU 分配

  • 系统会为每个探测分配 CPU。
  • 所有探测都按 CPU 和内存用量计费，但不需要支付基于请求的费用。

探测要求和行为

探测类型 要求 行为
TCP 启动 无 默认情况下，Cloud Run 会建立 TCP 连接，以便在指定端口上打开 TCP 套接字。如果 Cloud Run 无法建立连接，则表示探测失败。

如果启动探测在指定时间 (failureThreshold * periodSeconds) 内未成功（最大值为 240）几秒钟，容器会关闭。另请参阅 TCP 默认值。
HTTP 启动 创建 HTTP 健康检查端点
使用 HTTP/1		 配置探测后，Cloud Run 会向服务健康检查端点发出 HTTP GET 请求（例如 /ready）。200 和 400 之间的任何响应都表示成功，其他响应均表示失败。

如果启动探测在指定时间 (failureThreshold * periodSeconds) 内未成功（不超过 240 秒），容器将关闭。

如果 HTTP 启动探测在指定时间内成功，并且您已配置 HTTP 活跃性探测，则 HTTP 活跃性探测会启动。
HTTP 活跃性 创建 HTTP 健康检查端点
使用 HTTP/1		 活跃性探测仅在启动探测成功后启动。配置探测并且任何启动探测成功后，Cloud Run 会向服务健康检查端点发出 HTTP GET 请求（例如 /health）。200 和 400 之间的任何响应都表示成功，其他响应均表示失败。

如果活跃性探测在指定时间内 (failureThreshold * periodSeconds) 未成功，则容器会通过 SIGKILL 信号关闭。容器仍在处理的所有剩余请求都会终止，并且 HTTP 状态代码为 503。容器关停后，Cloud Run 自动扩缩功能将启动新的容器实例。
gRPC 启动 在 Cloud Run 服务中实现 gRPC 健康检查协议 如果启动探测在指定时间 (failureThreshold * periodSeconds) 内未成功（不超过 240 秒），则容器会关停。
gRPC 活跃性 在 Cloud Run 服务中实现 gRPC 健康检查协议 如果您配置了 gRPC 启动探测，则活跃性探测仅在启动探测成功后启动。

活跃性探测配置后，并且任何启动探测成功后，Cloud Run 会向服务发出健康检查请求。

如果活跃性探测在指定时间 (failureThreshold * periodSeconds) 内未成功，则容器会使用 SIGKILL 信号关停。容器关停后，Cloud Run 自动扩缩功能将启动新的容器实例。

配置探测

任何配置更改都会导致新修订版本的创建。后续修订版本也将自动采用此配置设置，除非您进行了明确更新。

您可以使用 Google Cloud 控制台、YAML 或 Terraform 配置 HTTP、TCP 和 gRPC 探测：

控制台

重要提示：如果您要为 Cloud Run 服务配置 HTTP 探测，则还必须在服务代码中添加 HTTP 健康检查端点以响应探测。如果要配置 gRPC 探测，则还必须在 Cloud Run 服务中实现 gRPC 健康检查协议。

  1. 在 Google Cloud 控制台中，转到 Cloud Run 页面。

    转到 Cloud Run

  2. 对于新服务，展开容器、卷、网络、安全性以显示健康检查选项。对于现有服务，请点击要配置的服务，然后点击修改和部署以显示健康检查选项。

  3. 在容器部分，请转到健康检查然后点击添加健康检查以打开添加健康检查配置面板。

  4. 从选择健康检查类型菜单中，选择要添加的健康检查的类型，例如启动检查或活跃性检查。

  5. 从选择探测类型菜单中，选择要使用的探测类型，例如 HTTP 或 gRPC。此时会显示探测配置表单。

  6. 请注意，探测配置因探测类型而异。配置探测设置：

    • 如果您使用的是 HTTP 探测：
      • 确保您的服务使用 HTTP/1（Cloud Run 默认值），而不是 HTTP/2。
      • 使用路径字段指定端点的相对路径，例如 /。
      • 选中 HTTP 标头复选框以指定可选的自定义标头。然后在名称字段中指定标头名称，在值字段中指定标头值。点击添加 HTTP 标头以指定更多标头。
    • 对于端口，指定用于服务的容器端口。
    • 对于初始延迟时间，指定容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • 对于周期，指定执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
    • 对于失败阈值，指定在关停容器之前重试探测的次数。默认值为 3。
    • 对于超时，指定等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。

  7. 点击添加以添加新的阈值

YAML

重要提示：如果您要为 Cloud Run 服务配置 HTTP 探测，则还必须在服务代码中添加端点以响应探测。如果要配置 gRPC 探测，则还必须在 Cloud Run 服务中实现 gRPC 健康检查协议。

TCP 启动

  1. 如果您要创建新的服务，请跳过此步骤。如果您要更新现有服务，请下载其 YAML 配置： 
    gcloud run services describe SERVICE --format export > service.yaml

  2. 配置 startupProbe 属性，如下所示：

    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

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址格式为 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • （可选）应将 CONTAINER_PORT 设置为用于您的服务的容器端口。
    • 将 DELAY 替换为容器启动后执行首次探测之前等待的时长（秒数）。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • （可选）将 TIMEOUT 替换为等待探测超时的时长（秒数）。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
    • 将 THRESHOLD 替换为关停容器之前重试探测的次数。默认值为 3。
    • 将 PERIOD 替换为要在其中执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

HTTP 启动

  1. 如果您要创建新的服务，请跳过此步骤。如果您要更新现有服务，请下载其 YAML 配置： 
    gcloud run services describe SERVICE --format export > service.yaml

  2. 确保您的服务使用 HTTP/1（Cloud Run 默认值），而不是 HTTP/2。

  3. 配置 startupProbe 属性，如下所示：

    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

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址格式为 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • 将 PATH 替换为 HTTP 端点的相对路径，例如 /ready。
    • （可选）应将 CONTAINER_PORT 设置为用于您的服务的容器端口。
    • （可选）httpHeaders 可用于使用 HEADER_NAME 和 HEADER_VALUE 字段提供多个或重复的自定义标头，如下所示。
    • （可选）将 DELAY 替换为容器启动后执行首次探测之前等待的时长（秒数）。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • （可选）将 TIMEOUT 替换为等待探测超时的时长（秒数）。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
    • （可选）将 THRESHOLD 替换为在关闭容器之前重试探测的次数。默认值为 3。
    • （可选）将 PERIOD 替换为执行探测的周期（以秒为单位）。 例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
  4. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

HTTP 活跃性

  1. 如果您要创建新的服务，请跳过此步骤。如果您要更新现有服务，请下载其 YAML 配置： 
    gcloud run services describe SERVICE --format export > service.yaml

  2. 确保您的服务使用 HTTP/1（Cloud Run 默认值），而不是 HTTP/2。

  3. 配置 livenessProbe 属性，如下所示：

    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

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址格式为 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • 将 PATH 替换为 HTTP 端点的相对路径，例如 /ready。
    • （可选）应将 CONTAINER_PORT 设置为用于您的服务的容器端口。
    • （可选）httpHeaders 可用于使用 HEADER_NAME 和 HEADER_VALUE 字段提供多个或重复的自定义标头，如下所示。
    • （可选）将 DELAY 替换为容器启动后执行首次探测之前等待的时长（秒数）。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • （可选）将 TIMEOUT 替换为等待探测超时的时长（秒数）。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 3600 之间的值。默认值为 1。
    • （可选）将 THRESHOLD 替换为在关闭容器之前重试探测的次数。默认值为 3。
    • （可选）将 PERIOD 替换为执行探测的周期（以秒为单位）。 例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3600 秒之间的值。默认值为 10 秒。
  4. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

gRPC 启动

  1. 如果您要创建新的服务，请跳过此步骤。如果您要更新现有服务，请下载其 YAML 配置： 
    gcloud run services describe SERVICE --format export > service.yaml

  2. 配置 startupProbe 属性，如下所示：

    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

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址格式为 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • （可选）GRPC_SERVICE。如果设置了此属性，则在调用 grpc.health.v1.Health.Check RPC 时，它会用于 grpc.health.v1.HealthCheckRequest 的服务字段。
    • （可选）应将 CONTAINER_PORT 设置为用于您的服务的容器端口。
    • （可选）将 DELAY 替换为容器启动后执行首次探测之前等待的时长（秒数）。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • （可选）将 TIMEOUT 替换为等待探测超时的时长（秒数）。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
    • （可选）将 THRESHOLD 替换为在关闭容器之前重试探测的次数。默认值为 3。
    • （可选）将 PERIOD 替换为执行探测的周期（以秒为单位）。 例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

gRPC 活跃性

  1. 如果您要创建新的服务，请跳过此步骤。如果您要更新现有服务，请下载其 YAML 配置： 
    gcloud run services describe SERVICE --format export > service.yaml

  2. 配置 livenessProbe 属性，如下所示：

    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

    替换

    • 将 SERVICE 替换为您的 Cloud Run 服务的名称。
    • 将 IMAGE_URL 替换为对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。 如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址格式为 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG
    • （可选）应将 CONTAINER_PORT 设置为用于您的服务的容器端口。
    • （可选）GRPC_SERVICE。如果设置了此属性，则在调用 grpc.health.v1.Health.Check RPC 时，它会用于 grpc.health.v1.HealthCheckRequest 的服务字段。
    • （可选）将 DELAY 替换为容器启动后执行首次探测之前等待的时长（秒数）。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • （可选）将 TIMEOUT 替换为等待探测超时的时长（秒数）。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 3600 之间的值。默认值为 1。
    • （可选）将 THRESHOLD 替换为在关闭容器之前重试探测的次数。默认值为 3。
    • （可选）将 PERIOD 替换为要在其中执行探测的时间段（以秒为单位）。 例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3600 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

Terraform

重要提示：如果您要为 Cloud Run 服务配置 HTTP 探测，则还必须在服务代码中添加端点以响应探测。如果要配置 gRPC 探测，则还必须在 Cloud Run 服务中实现 gRPC 健康检查协议。

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。

TCP 启动

使用 startup_probe 特性配置 Cloud Run 服务，如下所示：

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-healthcheck"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      startup_probe {
        failure_threshold     = 5
        initial_delay_seconds = 10
        timeout_seconds       = 3
        period_seconds        = 3

        tcp_socket {
          port = 8080
        }
      }
    }
  }
}

HTTP 启动

确保您的服务使用 HTTP/1（Cloud Run 默认值），而不是 HTTP/2。

使用 startup_probe 特性配置 Cloud Run 服务，如下所示：

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-healthcheck"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      startup_probe {
        failure_threshold     = 5
        initial_delay_seconds = 10
        timeout_seconds       = 3
        period_seconds        = 3

        http_get {
          path = "/"
          # Custom headers to set in the request
          # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#http_headers
          http_headers {
            name  = "Access-Control-Allow-Origin"
            value = "*"
          }
        }
      }
    }
  }
}

HTTP 活跃性

确保您的服务使用 HTTP/1（Cloud Run 默认值），而不是 HTTP/2。

使用 liveness_probe 特性配置 Cloud Run 服务，如下所示：

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-healthcheck"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      liveness_probe {
        failure_threshold     = 5
        initial_delay_seconds = 10
        timeout_seconds       = 3
        period_seconds        = 3

        http_get {
          path = "/"
          # Custom headers to set in the request
          # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_service#http_headers
          http_headers {
            name  = "Access-Control-Allow-Origin"
            value = "*"
          }
        }
      }
    }
  }
}

gRPC 启动

使用 startup_probe 特性配置 Cloud Run 服务，如下所示：

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-healthcheck"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    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"
        }
      }
    }
  }
}

gRPC 活跃性

使用 liveness_probe 特性配置 Cloud Run 服务，如下所示：

resource "google_cloud_run_v2_service" "default" {
  name     = "cloudrun-service-healthcheck"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # Note: Change to the name of your image
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      liveness_probe {
        failure_threshold     = 5
        initial_delay_seconds = 10
        timeout_seconds       = 3
        period_seconds        = 3

        # Note: Change to the name of your pre-existing grpc health status service
        grpc {
          service = "grpc.health.v1.Health"
        }
      }
    }
  }
}

创建 HTTP 健康检查端点

如果您为 Cloud Run 服务配置了 HTTP 启动探测或活跃性探测，则需要在服务代码中添加端点以响应探测。端点可以指定为任何名称（例如 /startup 或 /ready），但必须与您在探测配置中为 path 指定的值相匹配。例如，如果您为 HTTP 启动探测指定了 /ready，则您应按如下所示在探测配置中指定 path：

startupProbe:
  httpGet:
    path: /ready

HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。