為服務設定容器健康狀態檢查

Cloud Run 健康狀態檢查可確保容器執行個體正常運作，並能處理流量。透過 Cloud Run 健康狀態檢查，您可以自訂容器何時準備好接收要求，以及容器何時應視為健康狀態不佳而需要重新啟動。

用途

您可以設定下列類型的健康狀態檢查探針：

• 啟動探測作業會判斷容器是否已啟動，並準備好接受流量。

  • 設定啟動探測後，系統會停用有效性和完備性檢查，直到啟動探測判斷容器已啟動為止，以免干擾服務啟動。
  • 如果您對啟動緩慢的容器使用有效性檢查，啟動探測就特別有用，因為啟動探測可防止容器在啟動並執行前過早關閉。

• 有效性探測作業會判斷是否要重新啟動容器。

  • 如果發生錯誤，重新啟動容器可提高服務可用性。
  • Liveness 探測作業的目的是重新啟動無法以其他方式復原的個別執行個體。這類事件主要用於無法復原的執行個體故障，例如服務正在執行但無法繼續運作的死結。您可以使用自訂機構政策，為每個容器設定存活探查。
  • 如果服務發生重複探查失敗的情況，Cloud Run 會限制執行個體重新啟動，避免發生不受控的當機迴圈。

• 完備性探測 (預覽版)

  完備性探測會判斷 Cloud Run 服務中的執行個體何時應處理流量。容器的啟動探測作業成功通過後，系統就會開始進行完備性檢查。如果執行個體超出您設定的失敗閾值，導致就緒探查失敗，Cloud Run 就會停止將新流量傳送至該執行個體。Cloud Run 不會終止執行個體，且執行個體再次通過就緒探測時，系統會將流量傳回該執行個體。

設定啟動探測

變更任何設定都會建立新的修訂版本。除非您明確做出更新，改變這項設定，否則後續的修訂版本也會自動取得這個設定。

您可以使用 Google Cloud 控制台、YAML 或 Terraform 設定 HTTP、TCP 和 gRPC 探針：

控制台

1. 前往 Google Cloud 控制台的「Cloud Run」頁面：

   前往 Cloud Run

2. 如果是新服務，請展開「Container(s), Volumes, Networking, Security」，顯示健康狀態檢查選項。如果是現有服務，請按一下要設定的服務，然後按一下「編輯並部署」，顯示健康狀態檢查選項。

3. 在「Container(s)」(容器) 部分中，前往「Health checks」(健康狀態檢查)，然後按一下「Add health check」(新增健康狀態檢查)，開啟「Add health check」(新增健康狀態檢查)設定面板。

4. 在「選取健康狀態檢查類型」選單中，選取「啟動檢查」。

5. 在「選取探測類型」選單中，選取要使用的探測類型，例如 HTTP 或 gRPC。系統會顯示探針設定表單。

6. 探針設定會因探針類型而異。設定探針：

   • 如果您使用 HTTP 探測：

     • 在服務程式碼中新增 HTTP/1 端點 (Cloud Run 預設端點，而非 HTTP/2)，以回應探測作業。端點名稱 (例如 /startup、/health 或 /are_you_ready) 必須與探測設定中的 path 相符。HTTP 健康狀態檢查端點可從外部存取，並遵循與任何其他外部公開 HTTP 服務端點相同的原則。

     • 使用「路徑」欄位指定端點的相對路徑，例如 /。

     • 選取「HTTP 標頭」核取方塊，指定選用的自訂標頭。在「名稱」欄位中指定標頭名稱，並在「值」欄位中指定標頭值。按一下「新增 HTTP 標頭」，指定更多標頭。

   • 如果您使用 gRPC 探測：

     • 確認容器映像檔實作 gRPC 健康狀態檢查通訊協定。

   • 在「Port」(通訊埠) 部分，指定服務使用的容器通訊埠。

   • 在「初始延遲」中，指定容器啟動後到執行第一項探測作業之間，這段時間間隔的秒數。請指定介於 0 秒到 240 秒之間的值。預設值為 0 秒。

   • 在「Period」(週期) 中，指定執行探查的週期 (以秒為單位)。例如 2，代表每 2 秒執行一次探查。指定介於 1 秒到 240 秒之間的值。預設值為 10 秒。

   • 在「Failure threshold」(失敗門檻)，指定關閉容器前重新嘗試探測的次數。預設值為 3。

   • 在「Timeout」(逾時)，指定要等待探測逾時的秒數。這個值不得超過為 periodSeconds 指定的值。請指定介於 1 到 240 之間的值。預設值為 1。

7. 按一下「新增」即可新增門檻。

8. 按一下 [Create] (建立) 或 [Deploy] (部署)。

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 Socket。如果 Cloud Run 無法建立連線，表示發生故障。 如果啟動探針未在指定時間 (failureThreshold * periodSeconds) 內成功，且該時間不得超過 240 秒，系統就會關閉容器。另請參閱「TCP 預設值」。
HTTP 啟動	建立 HTTP 健康狀態檢查端點 使用 HTTP/1	設定探測後，Cloud Run 會對健康狀態檢查端點發出 HTTP GET 要求 (例如 /health)。任何 2XX 或 3XX 回應都視為成功，其他則視為失敗。 如果啟動探測在指定時間 (failureThreshold * periodSeconds) 內未成功 (不得超過 240 秒)，容器就會關閉。 如果 HTTP 啟動探測在指定時間內成功，且您已設定 HTTP 存活探測，系統就會啟動 HTTP 存活探測。
gRPC 啟動	在 Cloud Run 服務中實作 gRPC 健康狀態檢查通訊協定	如果啟動探測在指定時間 (failureThreshold * periodSeconds) 內失敗 (不得超過 240 秒)，系統會關閉容器。

設定 liveness 探測

變更任何設定都會建立新的修訂版本。除非您明確做出更新，改變這項設定，否則後續的修訂版本也會自動取得這個設定。

您可以使用 Google Cloud 控制台、YAML 或 Terraform 設定 HTTP 和 gRPC 探針：

控制台

1. 前往 Google Cloud 控制台的「Cloud Run」頁面：

   前往 Cloud Run

2. 如果是新服務，請展開「Container(s), Volumes, Networking, Security」，顯示健康狀態檢查選項。如果是現有服務，請按一下要設定的服務，然後按一下「編輯並部署」，顯示健康狀態檢查選項。

3. 在「Container(s)」(容器) 部分中，前往「Health checks」(健康狀態檢查)，然後按一下「Add health check」(新增健康狀態檢查)，開啟「Add health check」(新增健康狀態檢查)設定面板。

4. 從「選取健康狀態檢查類型」選單中，選取「活體檢查」。

5. 在「選取探測類型」選單中，選取要使用的探測類型，例如 HTTP 或 gRPC。系統會顯示探針設定表單。

6. 探針設定會因探針類型而異。設定探針：

   • 如果您使用 HTTP 探測：

     • 在服務程式碼中新增 HTTP/1 端點 (Cloud Run 預設端點，而非 HTTP/2)，以回應探測作業。端點名稱 (例如 /startup、/health 或 /are_you_ready) 必須與探測設定中的 path 相符。HTTP 健康狀態檢查端點可從外部存取，並遵循與任何其他外部公開 HTTP 服務端點相同的原則。

     • 使用「路徑」欄位指定端點的相對路徑，例如 /。

     • 選取「HTTP 標頭」核取方塊，指定選用的自訂標頭。在「名稱」欄位中指定標頭名稱，並在「值」欄位中指定標頭值。按一下「新增 HTTP 標頭」，指定更多標頭。

   • 如果您使用 gRPC 探測：

     • 確認容器映像檔實作 gRPC 健康狀態檢查通訊協定。

   • 在「Port」(通訊埠) 部分，指定服務使用的容器通訊埠。

   • 在「初始延遲」中，指定容器啟動後到執行第一項探測作業之間，這段時間間隔的秒數。請指定介於 0 秒到 240 秒之間的值。預設值為 0 秒。

   • 在「Period」(週期) 中，指定執行探查的週期 (以秒為單位)。例如 2，代表每 2 秒執行一次探查。請指定介於 1 秒到 3600 秒之間的值。預設值為 10 秒。

   • 在「Failure threshold」(失敗門檻)，指定關閉容器前重新嘗試探測的次數。預設值為 3。

   • 在「Timeout」(逾時)，指定探測逾時前的等待秒數。這個值不得超過為 periodSeconds 指定的值。請指定介於 1 到 3600 之間的值。預設值為 1。

7. 按一下「新增」即可新增門檻。

8. 按一下 [Create] (建立) 或 [Deploy] (部署)。

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 到 3600 之間的值。預設值為 1。
• (選用步驟) PERIOD：執行探查的週期 (以秒為單位)。例如 2，每 2 秒執行一次探查。請指定介於 1 秒到 3600 秒之間的值。預設值為 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 到 3600 之間的值。預設值為 1。
• (選用步驟) PERIOD：執行探查的週期 (以秒為單位)。例如 2，每 2 秒執行一次探查。請指定介於 1 秒到 3600 秒之間的值。預設值為 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 到 3600 之間的值。預設值為 1。
   • (選用步驟) PERIOD：執行探查的週期 (以秒為單位)。例如 2，每 2 秒執行一次探查。請指定介於 1 秒到 3600 秒之間的值。預設值為 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 到 3600 之間的值。預設值為 1。
   • (選用步驟) PERIOD：執行探查的週期 (以秒為單位)。例如 2，每 2 秒執行一次探查。請指定介於 1 秒到 3600 秒之間的值。預設值為 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 會對健康狀態檢查端點發出 HTTP GET 要求 (例如 /health)。任何 2XX 或 3XX 回應都表示成功，其他則表示失敗。 如果存活探測在指定時間內 (failureThreshold * periodSeconds) 未成功，系統會使用 SIGKILL 信號關閉容器。容器仍在處理的任何其餘要求都會終止，並傳回 HTTP 狀態碼 503。容器關閉後，Cloud Run 自動調度功能會啟動新的容器執行個體。
gRPC 存活度	在 Cloud Run 服務中實作 gRPC 健康狀態檢查通訊協定	如果設定 gRPC 啟動探測，只有在啟動探測成功後，存活探測才會開始。 設定存活探測後，只要啟動探測成功，Cloud Run 就會向服務發出健康狀態檢查要求。 如果存活探測在指定時間 (failureThreshold * periodSeconds) 內未成功，系統會使用 SIGKILL 信號關閉容器。容器關閉後，Cloud Run 自動調度功能會啟動新的容器執行個體。

設定 readiness 探測

變更任何設定都會建立新的修訂版本。除非您明確做出更新，改變這項設定，否則後續的修訂版本也會自動取得這個設定。

預先發布版 — Readiness probes

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

就緒探針有下列限制：

• 啟用工作階段親和性後，即使就緒檢查失敗，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. 如果是新服務，請展開「Container(s), Volumes, Networking, Security」，顯示健康狀態檢查選項。如果是現有服務，請按一下要設定的服務，然後按一下「編輯並部署」，顯示健康狀態檢查選項。

3. 在「Container(s)」(容器) 部分中，前往「Health checks」(健康狀態檢查)，然後按一下「Add health check」(新增健康狀態檢查)，開啟「Add health check」(新增健康狀態檢查)設定面板。

4. 從「選取健康狀態檢查類型」選單中，選取「準備程度檢查」。

5. 在「選取探測類型」選單中，選取要使用的探測類型，例如 HTTP 或 gRPC。系統會顯示探針設定表單。

6. 探針設定會因探針類型而異。設定探針：

   • 如果您使用 HTTP 探測：

     • 在服務程式碼中新增 HTTP/1 端點 (Cloud Run 預設端點，而非 HTTP/2)，以回應探測作業。端點名稱 (例如 /startup、/health 或 /are_you_ready) 必須與探測設定中的 path 相符。HTTP 健康狀態檢查端點可從外部存取，並遵循與任何其他外部公開 HTTP 服務端點相同的原則。

     • 使用「路徑」欄位指定端點的相對路徑，例如 /are_you_ready。預設路徑為 /。

   • 如果您使用 gRPC 探測：

     • 確認容器映像檔實作 gRPC 健康狀態檢查通訊協定。

   • 在「Port」(通訊埠) 部分，指定服務的容器通訊埠。預設通訊埠為主要連入通訊埠。

   • 在「Period」(週期) 中，指定執行探查的週期 (以秒為單位)。例如 2，每 2 秒執行一次探查。 請指定介於 1 到 300 之間的值。預設值為 10 秒。

   • 在「Success threshold」(成功門檻)，指定探測失敗後，至少要連續成功幾次，才算成功。預設值為 2。

   • 針對「失敗門檻」，請指定在回報失敗前要重試探測的次數，這會導致執行個體停止接收流量。預設值為 3。

   • 在「Timeout」(逾時)，指定探測逾時前的等待秒數。這個值不得超過為 periodSeconds 指定的值。請指定介於 1 到 300 之間的值。預設值為 1。

7. 按一下「新增」即可新增門檻。

8. 按一下 [Create] (建立) 或 [Deploy] (部署)。

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 和記憶體用量計費，但不會根據要求收費。

後續步驟

• 瞭解如何設定 gRPC 健康狀態檢查通訊協定。