Ingress ヘルスチェックのトラブルシューティング

このページでは、Google Kubernetes Engine（GKE）の Ingress のヘルスチェックに関連する問題を解決する方法について説明します。

さらにサポートを必要とされる場合は、Cloud カスタマーケアにお問い合わせください。

Ingress ヘルスチェックの仕組みを理解する

トラブルシューティングの手順に進む前に、GKE でのヘルスチェックの仕組みと、ヘルスチェックを正常に行うための考慮事項を理解しておくと役に立ちます。

デフォルトの Ingress コントローラを使用して Ingress によって 1 つ以上の Service を公開すると、GKE によって従来のアプリケーション ロードバランサまたは内部アプリケーション ロードバランサが作成されます。こうしたロードバランサでは、いずれも 1 つの URL マップで複数のバックエンド サービスがサポートされます。各バックエンド サービスは Kubernetes Service に対応し、各バックエンド サービスは Google Cloud ヘルスチェックを参照する必要があります。このヘルスチェックはクラスタの外部で実装されるため、Kubernetes の liveness Probe または readiness Probe とは異なります。

ロードバランサのヘルスチェックは、バックエンド サービスごとに指定されます。ロードバランサのすべてのバックエンド サービスに同じヘルスチェックを実施できますが、ロードバランサ全体に対してはヘルスチェック リファレンスが（Ingress オブジェクト自体では）指定されません。

GKE は、次のいずれかの方法に基づいてヘルスチェックを作成します。

  • BackendConfig CRD: Service がロードバランサとやり取りする方法を正確に制御できるカスタム リソース定義（CRD）。BackendConfig CRD を使用すると、対応するバックエンド サービスに関連付けられたヘルスチェックのカスタム設定を指定できます。これらのカスタム設定により、従来のアプリケーション ロードバランサと Ingress によって作成された内部アプリケーション ロードバランサの両方のヘルスチェックをより柔軟に制御できます。
  • Readiness プローブ: Pod 内のコンテナがトラフィックを処理する準備ができているかどうかを判断する診断チェック。GKE Ingress コントローラは、その Service のサービスを提供する Pod で使用されている readinessProbe に基づいて、Service のバックエンド サービスのヘルスチェックを作成します。パス、ポート、プロトコルなどのヘルスチェック パラメータは、readinessProbe の定義から導出できます。
  • デフォルト値: BackendConfig CRD を構成しない場合や、readinessProbe の属性を定義しない場合、このパラメータが使用されます。
ベスト プラクティス:

BackendConfig CRD を使用して、ロードバランサのヘルスチェック設定を細かく制御します。

GKE は、次の手順を使用して、Kubernetes Service に対応する各バックエンド サービスのヘルスチェックを作成します。

  • Service が healthCheck 情報を使用して BackendConfig CRD を参照する場合、GKE はそれを使用してヘルスチェックを作成します。このヘルスチェックの作成方法は、GKE Enterprise Ingress コントローラと GKE Ingress コントローラの両方でサポートされます。

  • Service が BackendConfig CRD を参照していない場合:

    • サービスを提供する Pod で readiness Probe にヘルスチェック パラメータとして解釈できる属性があるコンテナで Pod テンプレートを使用する場合、GKE でヘルスチェックのパラメータの一部またはすべてを推定できます。実装の詳細については、readiness Probe からのパラメータ、ヘルスチェック パラメータの作成に使用できる属性のリストについては、デフォルト パラメータと推定パラメータをご覧ください。readiness Probe からのパラメータの推定は、GKE Ingress コントローラでのみサポートされています。

    • Service のサービスを提供する Pod 用の Pod テンプレートに、ヘルスチェック パラメータとして解釈できる属性がある readinessProbe があるコンテナがない場合、ヘルスチェックの作成にデフォルト値が使用されます。GKE Enterprise Ingress コントローラと GKE Ingress コントローラの両方で、デフォルト値のみを使用してヘルスチェックを作成できます。

考慮事項

このセクションでは、BackendConfig CRD を構成する場合や、準備プローブを使用する場合に考慮すべき点について説明します。

BackendConfig CRD

BackendConfig CRD を構成する際は、次の点を考慮してください。

  • コンテナ ネイティブのロード バランシングを使用している場合は、BackendConfig マニフェストのヘルスチェック ポートが、サービスを提供する Pod の containerPort と一致していることを確認します。
  • インスタンス グループのバックエンドの場合、BackendConfig マニフェストのヘルスチェック ポートが、Service によって公開される nodePort と一致していることを確認します。
  • Ingress は、カスタム ヘルスチェック構成の gRPC をサポートしていません。BackendConfig は、HTTP、HTTPS、または HTTP2 プロトコルを使用したヘルスチェックの作成のみをサポートします。BackendConfig CRD でプロトコルを使用する方法の例については、gke-networking-recipes をご覧ください。

詳細については、BackendConfig CRD を使用する場合をご覧ください。

readinessProbe

HTTP または HTTPS ロード バランシングで GKE Ingress を使用する場合、GKE はヘルスチェック プローブを送信して、アプリケーションが正しく実行されているかどうかを判断します。次の条件を満たしている限り、これらのヘルスチェック プローブは、Pod の YAML 構成の spec.containers[].readinessProbe.httpGet.port セクションで定義した Pod の特定のポートに送信されます。

  • spec.containers[].readinessProbe.httpGet.port で指定された readiness Probe のポート番号は、アプリケーションがコンテナ内でリッスンしている実際のポートと一致する必要があります。このポートは、Pod 構成の containers[].spec.ports.containerPort フィールドで定義されています。
  • サービスを提供する Pod の containerPort は、Service の targetPort と一致する必要があります。これにより、トラフィックが Service から Pod の正しいポートに転送されます。
  • Ingress のサービス バックエンド ポートの仕様では、Service 構成の spec.ports[] セクションの有効なポートを参照する必要があります。これには、次の 2 つの方法があります。
    • Ingress の spec.rules[].http.paths[].backend.service.port.name は、対応する Service で定義された spec.ports[].name と一致します。
    • Ingress の spec.rules[].http.paths[].backend.service.port.number は、対応する Service で定義された spec.ports[].port と一致します。

ヘルスチェックの一般的な問題のトラブルシューティング

次のトラブルシューティングのフローチャートを使用して、ヘルスチェックの問題を特定します。

Ingress ヘルスチェックのトラブルシューティング。
図: ヘルスチェックのトラブルシューティング

このフローチャートでは、次のトラブルシューティングのガイダンスが問題の発生場所の特定に役立ちます。

  1. Pod の状態を調査する: ヘルスチェックが失敗した場合は、Service のサービスを提供する Pod のステータスを確認します。Pod が実行されておらず、正常な場合:

    • Pod のログで、実行を妨げているエラーや問題がないか確認します。
    • readiness プローブと liveness プローブのステータスを確認します。

  2. ヘルスチェックのロギング: ヘルスチェックのロギングが有効になっていることを確認します。

  3. ファイアウォールの構成を確認する: ファイアウォール ルールで、ヘルスチェック プローブが Pod に到達できるようにします。入力されていない場合は、次の手順を実行します。

    • ファイアウォール ルールをチェックして、ヘルスチェック プローブの IP アドレス範囲からの受信トラフィックが許可されていることを確認します。
    • これらの IP アドレス範囲に対応するように、必要に応じてファイアウォール ルールを調整します。

  4. パケット キャプチャを分析する: ファイアウォールが正しく構成されている場合は、パケット キャプチャを実行して、アプリケーションがヘルスチェックに応答しているかどうかを確認します。パケット キャプチャで正常なレスポンスが示された場合は、Google Cloud サポートにお問い合わせください。

  5. アプリケーションのトラブルシューティング: パケット キャプチャに成功したレスポンスが表示されない場合は、アプリケーションがヘルスチェック リクエストに正しく応答していない理由を調査します。ヘルスチェックが Pod の正しいパスとポートをターゲットにしていることを確認し、アプリケーション ログ、構成ファイル、依存関係を調べます。エラーが見つからない場合は、Google Cloud サポートにお問い合わせください。

ヘルスチェックに応答しないアプリケーション

構成されたパスとポートでのヘルスチェック中に、アプリケーションが想定されるステータス コード（HTTP の場合は 200 OK、TCP の場合は SYN、ACK）で応答しない。

アプリケーションがヘルスチェックに正しく応答しない場合は、次のいずれかの理由が考えられます。

  • ネットワーク エンドポイント グループ（NEG）:
    • アプリケーションが Pod 内で正しく実行されていない。
    • アプリケーションが、構成されたポートまたはパスでリッスンしていない。
    • ヘルスチェックが Pod に到達できないネットワーク接続の問題がある。
  • インスタンス グループ:
    • インスタンス グループ内のノードが正常ではありません。
    • アプリケーションがノードで正しく実行されていない。
    • ヘルスチェック リクエストがノードに到達していません。

ヘルスチェックが失敗する場合は、設定に応じて、次の手順で問題のトラブルシューティングを行います。

NEG の場合:

  1. kubectl exec を使用して Pod にアクセスします。

    kubectl exec -it pod-name -- command

    フラグ -it は、インタラクティブ ターミナル セッションを提供します（i はインタラクティブ、t は TTY）。

    次のように置き換えます。

    • pod-name: Pod の名前。
    • command: Pod 内で実行するコマンド。最も一般的なコマンドは、対話型シェルを取得する bash または sh です。

  2. curl コマンドを実行して、接続とアプリケーションの応答性をテストします。

    • curl localhost:<Port>/<Path>
    • curl -v http://<POD_IP>/[Path configured in HC]
    • curl http://localhost/[Path configured in HC]

インスタンス グループの場合:

  1. ノードが正常で、デフォルトのヘルスチェック プローブに応答していることを確認します。
  2. ノードが正常で、アプリケーション Pod が応答しない場合は、アプリケーションをさらに調査します。
  3. リクエストが Pod に到達しない場合は、GKE ネットワークの問題である可能性があります。詳しくは Google Cloud サポートにお問い合わせください。

Pod の準備プローブの編集中にエラーが発生する

Pod の readinessProbe を編集してヘルスチェック パラメータを変更しようとすると、次のようなエラーが発生します。

Pod "pod-name" is invalid: spec: Forbidden: pod updates may not change fields

Ingress（および対応するロードバランサ）にすでにリンクされている Service に関連付けられている Pod の readinessProbe を変更しても、GKE はロードバランサのヘルスチェック構成を自動的に更新しません。これにより、Pod の準備状況チェックとロードバランサのヘルスチェックが一致せず、ヘルスチェックが失敗します。

この問題を解決するには、Pod と Ingress リソースを再デプロイします。これにより、GKE はロードバランサとそのヘルスチェックを再作成し、新しい準備プローブ設定を組み込みます。

デプロイとロードバランサが起動しない

デプロイが開始されず、Ingress コントローラのロードバランサの背後にあるバックエンド サービスが異常とマークされている場合は、readinessProbe の失敗が原因である可能性があります。

準備プローブの失敗に関する次のエラー メッセージが表示される場合があります。

Readiness probe failed: connection refused

Pod 内のアプリケーションが、Pod の YAML 構成で構成された準備プローブに正しく応答しません。これは、アプリケーションが正しく起動しない、間違ったポートでリッスンしている、初期化中にエラーが発生したなど、さまざまな理由が考えられます。

この問題を解決するには、次の手順でアプリの構成や動作の不一致を調査して修正します。

  • アプリケーションが正しく構成され、readinessProbe パラメータで指定されたパスとポートで応答していることを確認します。
  • アプリケーション ログを確認し、起動に関する問題やエラーのトラブルシューティングを行います。
  • Pod 構成の containerPort が、Service の targetPort と Ingress で指定されたバックエンド ポートと一致していることを確認します。

自動上り（内向き）ファイアウォール ルールがない

Ingress リソースを作成しましたが、トラフィックがバックエンド サービスに到達しません。

通常は Ingress リソースの作成時に GKE によって作成される自動 Ingress ファイアウォール ルールが存在しない場合や、誤って削除されている場合。

バックエンド サービスへの接続を復元する手順は次のとおりです。

  • VPC ネットワークに自動上り（内向き）ファイアウォール ルールが存在することを確認します。
  • ルールがない場合は、手動で再作成するか、Ingress リソースを削除して再作成して、自動作成をトリガーできます。
  • Ingress リソースで定義されているように、ファイアウォール ルールで適切なポートとプロトコルのトラフィックが許可されていることを確認します。

BackendConfig マニフェストで使用されているプロトコルが正しくない

TCP タイプのプロトコルで BackendConfig CRD を構成すると、次のエラーが表示されます。

Error syncing to GCP: error running backend syncing routine:
error ensuring health check: Protocol "TCP" is not valid, must be one of ["HTTP","HTTPS","HTTP2"]'

BackendConfig は、HTTP、HTTPS、または HTTP/2 プロトコルのみを使用したヘルスチェックの作成をサポートしています。詳細については、HTTP、HTTPS、HTTP/2 での成功基準をご覧ください。

次のステップ

単一クラスタで Ingress のカスタム ヘルスチェックを設定するには、GKE ネットワーク レシピをご覧ください。