コンテナのヘルスチェックを構成する（サービス）

HTTP、TCP、gRPC の起動プローブと、新規および既存の Cloud Run サービスに対する HTTP と gRPC のライブネス プローブを構成できます。構成は、プローブの種類によって異なります。

なお、TCP 起動プローブは、新しい Cloud Run サービス用に自動的に構成されますのでご注意ください。詳しくは、デフォルトの TCP 起動プローブをご覧ください。

ユースケース

構成できるヘルスチェック プローブには次の 2 種類があります。

  • ライブネス プローブは、コンテナを再起動するかどうかを判断します。

    • この場合にコンテナを再起動すると、バグが発生したときにおけるサービスの可用性を高めることができます。
    • ライブネス プローブは、他の方法では復元できない個々のインスタンスを再起動することを目的としています。主に、回復不能なインスタンス障害に使用します。たとえば、サービスは実行されているが、処理が進まないデッドロックを捕捉する場合などです。

  • 起動プローブは、コンテナが起動し、トラフィックを受け入れる準備ができているかどうかを判断します。

    • 起動プローブを構成すると、コンテナが起動したと起動プローブが判断するまで、ライブネス チェックは無効になります。これにより、サービス起動時の干渉が防止されます。
    • 起動プローブは、開始が遅いコンテナでライブネス チェックを行う場合に特に役立ちます。これは、コンテナが起動して動作する前にシャットダウンされることを防ぐためです。

サービスで起動プローブまたはライブネス プローブの失敗が繰り返し発生すると、制御不能なクラッシュ ループを防ぐために、Cloud Run はインスタンスの再起動を制限するのでご注意ください。

デフォルトの TCP 起動プローブ

TCP 起動プローブは、デフォルト値を使用して新しい Cloud Run サービス用に自動的に構成されます。デフォルトのプローブは次のものと同等です。

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 はサービス ヘルスチェック エンドポイント（/ready など）に HTTP GET リクエストを送信します。200～400 のレスポンスはどれも成功であり、他のレスポンスは失敗を意味します。

起動プローブが指定時間（failureThreshold × periodSeconds）（最長で 240 秒）以内に成功しなかった場合、コンテナはシャットダウンされます。

HTTP 起動プローブが指定時間内に成功し、HTTP ライブネス プローブを構成している場合、HTTP ライブネス プローブが開始されます。
HTTP ライブネス HTTP ヘルスチェック エンドポイントを作成する
HTTP/1 を使用する		 ライブネス プローブは、起動プローブが成功した後にのみ開始されます。プローブの構成後、起動プローブが成功すると、Cloud Run はサービス ヘルスチェック エンドポイント（/health など）に HTTP GET リクエストを送信します。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 の自動スケーリングによって新しいコンテナ インスタンスが起動します。

プローブを構成する

構成を変更すると、新しいリビジョンが作成されます。明示的に更新しない限り、以降のリビジョンでも、この構成が自動的に設定されます。

HTTP、TCP、gRPC のプローブは、Google Cloud コンソール、YAML、または Terraform を使用して構成できます。

コンソール

重要: HTTP プローブ用に Cloud Run サービスを構成する場合は、プローブに応答するために、サービスコードに HTTP ヘルスチェック エンドポイントを追加する必要があります。gRPC プローブを構成する場合は、Cloud Run サービスに gRPC ヘルスチェック プロトコルを実装する必要があります。

  1. Google Cloud コンソールで [Cloud Run] ページに移動します。

    Cloud Run に移動

  2. 新しいサービスの場合は、[コンテナ、ボリューム、ネットワーキング、セキュリティ] を開いて、ヘルスチェック オプションを表示します。既存のサービスの場合は、構成するサービスをクリックし、[新しいリビジョンの編集とデプロイ] をクリックして、ヘルスチェック オプションを表示します。

  3. [コンテナ] セクションで [ヘルスチェック] に移動し、[ヘルスチェックを追加します] をクリックして、[ヘルスチェックを追加] 構成パネルを開きます。

  4. [ヘルスチェックの種類の選択] メニューから、追加するヘルスチェックの種類（起動、ライブネスなど）を選択します。

  5. [プローブタイプの選択] メニューで、使用するプローブのタイプ（HTTP や gRPC など）を選択すると、プローブ構成フォームが表示されます。

  6. プローブの構成はプローブの種類によって異なりますのでご注意ください。プローブ設定を構成します。

    • HTTP プローブを使用している場合:
      • サービスが HTTP/2 ではなく HTTP/1（Cloud Run のデフォルト）を使用していることを確認します。
      • [パス] フィールドに、エンドポイントへの相対パスを指定します（例: /）。
      • [HTTP ヘッダー] チェックボックスをオンにして、オプションのカスタム ヘッダーを指定します。[名前] フィールドにヘッダー名、[値] フィールドにヘッダー値を指定します。[HTTP ヘッダーを追加] をクリックして、他のヘッダーを指定します。
    • [ポート] に、サービスに使用するコンテナポートを指定します。
    • [初期遅延] に、コンテナが起動してから最初のプローブを実行するまでの待機時間を秒単位で指定します。0 秒～240 秒の値を指定します。デフォルト値は 0 秒です。
    • [期間] に、プローブを実行する期間（秒単位）を指定します。たとえば、2 秒ごとにプローブを実行する場合は 2 です。1 秒～240 秒の値を指定します。デフォルト値は 10 秒です。
    • [失敗しきい値] に、コンテナをシャットダウンする前にプローブを再試行する回数を指定します。デフォルト値は 3 です。
    • [タイムアウト] に、プローブがタイムアウトするまでの待機時間を秒単位で指定します。この値は、periodSeconds に指定された値を超えることはできません。1～240 の値を指定します。デフォルトは 1 です。

  7. [追加] をクリックして、新しいしきい値を追加します。

YAML

重要: HTTP プローブ用に Cloud Run サービスを構成する場合は、プローブに応答するために、サービスコードにエンドポイントを追加する必要があります。gRPC プローブを構成する場合は、Cloud Run サービスに gRPC ヘルスチェック プロトコルを実装する必要があります。

TPC 起動

  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 がすでに作成されている必要があります。URL の形式は 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/2 ではなく HTTP/1（Cloud Run のデフォルト）を使用していることを確認します。

  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 がすでに作成されている必要があります。URL の形式は 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/2 ではなく HTTP/1（Cloud Run のデフォルト）を使用していることを確認します。

  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 がすでに作成されている必要があります。URL の形式は 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～3,600 の値を指定します。デフォルトは 1 です。
    • （省略可）THRESHOLD は、コンテナをシャットダウンする前にプローブを再試行する回数に置き換えます。デフォルト値は 3 です。
    • （省略可）PERIOD は、プローブを実行する期間（秒単位）に置き換えます。たとえば、2 秒ごとにプローブを実行する場合は 2 です。1 秒～3,600 秒の値を指定します。デフォルト値は 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 がすでに作成されている必要があります。URL の形式は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG です。
    • GRPC_SERVICE は、ヘルスチェックを送信する gRPC サービスの名前に置き換えます。
    • （省略可）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 がすでに作成されている必要があります。URL の形式は LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG です。
    • （省略可）CONTAINER_PORT は、サービスに使用するコンテナポートに設定する必要があります。
    • GRPC_SERVICE は、ヘルスチェックを送信する gRPC サービスの名前に置き換えます。
    • （省略可）DELAY は、コンテナが開始された後、最初のプローブを実行するまでに待機する秒数に置き換えます。0 秒～240 秒の値を指定します。デフォルト値は 0 秒です。
    • （省略可）TIMEOUT は、プローブがタイムアウトするまでの待機時間（秒）に置き換えます。この値は、periodSeconds に指定された値を超えることはできません。1～3,600 の値を指定します。デフォルトは 1 です。
    • （省略可）THRESHOLD は、コンテナをシャットダウンする前にプローブを再試行する回数に置き換えます。デフォルト値は 3 です。
    • （省略可）PERIOD は、プローブを実行する期間（秒単位）に置き換えます。たとえば、2 秒ごとにプローブを実行する場合は 2 です。1 秒～3,600 秒の値を指定します。デフォルト値は 10 秒です。
  3. 次のコマンドを使用して、サービスを作成または更新します。
    gcloud run services replace service.yaml

Terraform

重要: HTTP プローブ用に Cloud Run サービスを構成する場合は、プローブに応答するために、サービスコードにエンドポイントを追加する必要があります。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"

  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/2 ではなく HTTP/1（Cloud Run のデフォルト）を使用していることを確認します。

次に示すように、startup_probe 属性を使用して Cloud Run サービスを構成します。

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

  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/2 ではなく HTTP/1（Cloud Run のデフォルト）を使用していることを確認します。

次に示すように、liveness_probe 属性を使用して Cloud Run サービスを構成します。

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

  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"

  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"

  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 起動プローブまたはライブネス プローブ用に Cloud Run サービスを構成する場合、プローブに応答するため、サービスコードにエンドポイントを追加する必要があります。エンドポイントには任意の名前（/startup、/ready など）を使用できますが、プローブ構成で path に指定した値と一致する必要があります。たとえば、HTTP 起動プローブに /ready を指定する場合は、次のようにプローブ構成で path を指定します。

startupProbe:
  httpGet:
    path: /ready

HTTP ヘルスチェック エンドポイントは外部からアクセスでき、外部に公開される他の HTTP サービス エンドポイントと同じ原則に従います。