为服务配置容器健康检查

Cloud Run 健康检查可确保容器实例正常运行并能够传送流量。借助 Cloud Run 健康检查，您可以自定义容器何时准备好接收请求，以及容器何时应视为运行状况不佳而需要重启。

使用场景

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

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

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

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

    • 在这种情况下，重启容器可以在出现错误时提高服务可用性。
    • 活跃性探测旨在重启无法以任何其他方式恢复的单个实例。它们应该主要用于不可恢复的实例故障，例如在服务正在运行但无法继续进行时捕获死锁。您可以使用自定义组织政策，要求每个容器都进行活跃性探测。
    • 当服务重复发生探测失败时，Cloud Run 会限制实例重启，以防止不受控制的崩溃循环。

  • 就绪性探测（预览版）

    就绪性探测用于确定 Cloud Run 服务中的实例何时应处理流量。容器的启动探测成功通过后，系统会开始进行就绪检查。如果实例的就绪状态探测失败次数超过您配置的失败阈值，Cloud Run 会停止向该实例发送新流量。当实例再次通过就绪状态探测时，Cloud Run 不会终止该实例，而是将流量重新发送到该实例。

配置启动探测

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

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

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run 页面：

    转到 Cloud Run

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

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

  4. 从选择健康检查类型菜单中，选择启动检查。

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

  6. 探测配置因探测类型而异。配置探测设置：

    • 如果您使用的是 HTTP 探测：

      • 在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

      • 使用路径字段指定端点的相对路径，例如 /。

      • 选中 HTTP 标头复选框以指定可选的自定义标头。在名称字段中指定标头名称，在值字段中指定标头值。点击添加 HTTP 标头以指定更多标头。

    • 如果您使用的是 gRPC 探测：

    • 对于端口，指定用于服务的容器端口。

    • 对于初始延迟时间，指定容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。

    • 对于周期，指定执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。

    • 对于失败阈值，指定在关停容器之前重试探测的次数。默认值为 3。

    • 对于超时，指定等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。 默认值为 1。

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

  8. 点击创建或部署。

gcloud

TCP 启动

运行以下命令：

  gcloud run deploy SERVICE \
      --image=IMAGE_URL \
      --startup-probe tcpSocket.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,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 秒。

HTTP 启动

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

运行以下命令：

  gcloud run deploy SERVICE \
      --image=IMAGE_URL \
      --startup-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,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 端点的相对路径，例如 /health。
  • 可选。CONTAINER_PORT：设置为用于您的服务的容器端口。
  • 可选。DELAY：容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
  • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。

gRPC 启动

确保您的容器映像实现了 gRPC 健康检查协议。

运行以下命令：

  gcloud run deploy SERVICE \
      --image=IMAGE_URL \
      --startup-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,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 秒。
  • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。

YAML

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 启动

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

  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:
          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 端点的相对路径，例如 /health。
    • 可选。CONTAINER_PORT：设置为用于您的服务的容器端口。
    • 可选。DELAY：容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
    • 可选：httpHeaders 可用于使用 HEADER_NAME 和 HEADER_VALUE 字段提供多个或重复的自定义标头，如下所示。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

gRPC 启动

确保您的容器映像实现了 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 秒。
    • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定 1 至 240 之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 240 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

Terraform

如需了解如何应用或移除 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、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

使用 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 = "*"
          }
        }
      }
    }
  }
}

gRPC 启动

确保您的容器映像实现了 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"
        }
      }
    }
  }
}

默认 TCP 启动探测

如果您未为新的 Cloud Run 服务明确配置 TCP 启动探测，Cloud Run 会自动配置 TCP 启动探测，并使用以下默认值：

startupProbe:
          timeoutSeconds: 240
          periodSeconds: 240
          failureThreshold: 1

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

启动探测要求和行为

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

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

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

如果 HTTP 启动探测在指定时间内成功，并且您配置了 HTTP 活跃性探测，则 HTTP 活跃性探测会启动。
gRPC 启动 在 Cloud Run 服务中实现 gRPC 健康检查协议 如果启动探测在指定时间 (failureThreshold * periodSeconds) 内未成功（不超过 240 秒），则容器会关停。

配置活跃探测

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

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

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run 页面：

    转到 Cloud Run

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

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

  4. 从选择健康检查类型菜单中，选择活跃性检查。

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

  6. 探测配置因探测类型而异。配置探测设置：

    • 如果您使用的是 HTTP 探测：

      • 在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

      • 使用路径字段指定端点的相对路径，例如 /。

      • 选中 HTTP 标头复选框以指定可选的自定义标头。在名称字段中指定标头名称，在值字段中指定标头值。点击添加 HTTP 标头以指定更多标头。

    • 如果您使用的是 gRPC 探测：

    • 对于端口，指定用于服务的容器端口。

    • 对于初始延迟时间，指定容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。

    • 对于周期，指定执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3600 秒之间的值。默认值为 10 秒。

    • 对于失败阈值，指定在关停容器之前重试探测的次数。默认值为 3。

    • 对于超时，指定等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 3600 之间的值。默认值为 1。

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

  8. 点击创建或部署。

gcloud

HTTP 活跃性

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

运行以下命令：

  gcloud run deploy SERVICE \
      --image=IMAGE_URL \
      --liveness-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,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 端点的相对路径，例如 /health。
  • 可选。CONTAINER_PORT：设置为用于您的服务的容器端口。
  • 可选。DELAY：容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
  • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 10 秒。

gRPC 活跃性

确保您的容器映像实现了 gRPC 健康检查协议。

运行以下命令：

  gcloud run deploy SERVICE \
      --image=IMAGE_URL \
      --liveness-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,initialDelaySeconds=DELAY,failureThreshold=THRESHOLD,timeoutSeconds=TIMEOUT,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 秒。
  • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 10 秒。

YAML

HTTP 活跃性

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

  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:
          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 端点的相对路径，例如 /health。
    • 可选。CONTAINER_PORT：设置为用于您的服务的容器端口。
    • 可选。DELAY：容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
    • 可选：httpHeaders 可用于使用 HEADER_NAME 和 HEADER_VALUE 字段提供多个或重复的自定义标头，如下所示。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 10 秒。
  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

gRPC 活跃性

确保您的容器映像实现了 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。
    • 可选。GRPC_SERVICE：如果设置了此属性，则在调用 grpc.health.v1.Health.Check RPC 时，它会用于 grpc.health.v1.HealthCheckRequest 的服务字段。
    • 可选。CONTAINER_PORT：用于服务的容器端口。
    • 可选。DELAY：容器启动后执行首次探测之前等待的秒数。指定一个介于 0 秒到 240 秒之间的值。默认值为 0 秒。
    • 可选。THRESHOLD：关停容器之前重试探测的次数。默认值为 3。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 秒到 3,600 秒之间的值。默认值为 10 秒。

  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

Terraform

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

HTTP 活跃性

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

使用 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 活跃性

确保您的容器映像实现了 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 活跃性 创建 HTTP 健康检查端点
使用 HTTP/1		 活跃性探测仅在启动探测成功后启动。配置探测并且任何启动探测成功后，Cloud Run 会向健康检查端点（例如 /health）发出 HTTP GET 请求。任何 2XX 或 3XX 响应都表示成功，其他响应均表示失败。

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

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

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

配置就绪性探测

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

就绪状态探测存在以下限制：

  • 如果您启用会话亲和性，即使实例的就绪状态检查失败，Cloud Run 也会继续向该实例发送请求。

  • 在就绪状态探测首次完成之前，Cloud Run 可能会向新启动的实例发送请求。

  • 如果您之前在 2025 年 11 月之前使用 Cloud Run Admin API v1 为 Cloud Run 服务配置了就绪状态探测，那么即使您为该服务部署了新配置，就绪状态检查也不会生效。这是因为该服务保留了较旧的配置。2025 年 11 月之后创建的服务或从未使用过就绪状态探测的服务不受影响。如需在受影响的服务上启用受支持的就绪状态探测，请执行以下操作：

    1. 部署一个新修订版本，以移除旧的就绪性探测定义。

    2. 部署另一个新修订版本，其中添加了相关的就绪状态探测定义。

    这些步骤会清除所有旧配置，并启用就绪状态探测功能。

您可以使用 Google Cloud 控制台、Google Cloud CLI 或 YAML 配置就绪状态探测：

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run 页面：

    转到 Cloud Run

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

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

  4. 从选择健康检查类型菜单中，选择就绪检查。

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

  6. 探测配置因探测类型而异。配置探测设置：

    • 如果您使用的是 HTTP 探测：

      • 在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

      • 使用路径字段指定端点的相对路径，例如 /are_you_ready。默认路径为 /。

    • 如果您使用的是 gRPC 探测：

    • 对于端口，指定用于服务的容器端口。默认端口是主入站端口。

    • 对于周期，指定执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。 指定一个介于 1 到 300 之间的值。默认值为 10 秒。

    • 对于成功阈值，请指定探测在失败后至少需连续成功几次才会被视为成功。默认值为 2。

    • 对于失败阈值，指定在报告失败之前重试探测的次数，这会导致实例停止接收流量。默认值为 3。

    • 对于超时，指定等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 300 之间的值。默认值为 1。

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

  8. 点击创建或部署。

gcloud

HTTP 就绪状态

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

运行以下命令：

gcloud beta run deploy SERVICE \
    --image=IMAGE_URL \
    --readiness-probe httpGet.path=PATH,httpGet.port=CONTAINER_PORT,successThreshold=SUCCESS_THRESHOLD,failureThreshold=FAILURE_THRESHOLD,timeoutSeconds=TIMEOUT,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 端点的相对路径，例如 /are_you_ready。默认路径为 /。
  • 可选。CONTAINER_PORT：用于服务的容器端口。默认端口是主要入站端口。
  • 可选。SUCCESS_THRESHOLD：探测在失败后至少需连续成功几次才会被视为成功。默认值为 2。
  • 可选。FAILURE_THRESHOLD：在报告失败之前重试探测的次数，这会导致实例停止接收流量。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 300 之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的周期（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 到 300 之间的值。默认值为 10 秒。

gRPC 就绪状态

确保您的容器映像实现了 gRPC 健康检查协议。

运行以下命令：

gcloud beta run deploy SERVICE \
    --image=IMAGE_URL \
    --readiness-probe grpc.port=CONTAINER_PORT,grpc.service=GRPC_SERVICE,successThreshold=SUCCESS_THRESHOLD,failureThreshold=FAILURE_THRESHOLD,timeoutSeconds=TIMEOUT,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 的服务字段。
  • 可选。SUCCESS_THRESHOLD：探测在失败后至少需连续成功几次才会被视为成功。默认值为 2。
  • 可选。FAILURE_THRESHOLD：在报告失败之前重试探测的次数，这会导致实例停止接收流量。默认值为 3。
  • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 300 之间的值。默认值为 1。
  • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 到 300 之间的值。默认值为 10 秒。

YAML

HTTP 就绪状态

在服务代码中添加 HTTP/1 端点（Cloud Run 默认值，而非 HTTP/2）以响应探测。端点名称（例如 /startup、/health 或 /are_you_ready）必须与探测配置中的 path 相匹配。HTTP 健康检查端点可从外部访问，并且遵循与外部公开的任何其他 HTTP 服务端点相同的原则。

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

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

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
    spec:
      containers:
      - image: IMAGE_URL
        readinessProbe:
          httpGet:
            path: PATH
            port: CONTAINER_PORT
          successThreshold: SUCCESS_THRESHOLD
          failureThreshold: FAILURE_THRESHOLD
          timeoutSeconds: TIMEOUT
          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 端点的相对路径，例如 /are_you_ready。默认路径为 /。
    • 可选。CONTAINER_PORT：用于服务的容器端口。默认端口是主要入站端口。
    • 可选。SUCCESS_THRESHOLD：探测在失败后至少需连续成功几次才会被视为成功。默认值为 2。
    • 可选。FAILURE_THRESHOLD：在报告失败之前重试探测的次数，这会导致实例停止接收流量。默认值为 3。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 300 之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 到 300 之间的值。默认值为 10 秒。

  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

gRPC 就绪状态

确保您的容器映像实现了 gRPC 健康检查协议。

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

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

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
    spec:
      containers:
      - image: IMAGE_URL
        readinessProbe:
          grpc:
            port: CONTAINER_PORT
            service: GRPC_SERVICE
          successThreshold: SUCCESS_THRESHOLD
          failureThreshold: FAILURE_THRESHOLD
          timeoutSeconds: TIMEOUT
          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 的服务字段。
    • 可选。SUCCESS_THRESHOLD：探测在失败后至少需连续成功几次才会被视为成功。默认值为 2。
    • 可选。FAILURE_THRESHOLD：在报告失败之前重试探测的次数，这会导致实例停止接收流量。默认值为 3。
    • 可选。TIMEOUT：等待探测超时的秒数。此值不能超过为 periodSeconds 指定的值。指定一个介于 1 到 300 之间的值。默认值为 1。
    • 可选。PERIOD：执行探测的时间段（以秒为单位）。例如，2 表示每 2 秒执行一次探测。指定一个介于 1 到 300 之间的值。默认值为 10 秒。

  3. 使用以下命令创建或更新服务： 
    gcloud run services replace service.yaml

CPU 分配

  • 当探测运行时，系统始终会分配 CPU。
  • 所有探测都按 CPU 和内存用量计费，但不需要支付基于请求的费用。

后续步骤