コンテンツにスキップ
|
Kong Gateway
3.7.x
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

ヘルスチェックとサーキットブレーカーのリファレンス

リングバランサを使ってAPIをKongにプロキシし、1つまたはそれ以上の ターゲットエンティティを含むアップストリームエンティティを追加して 構成することができます。それぞれのターゲットは異なるIPアドレス（またはホスト名）およびポートを 指しています。リングバランサはさまざまなターゲットの間でロードバランシングを行い、 アップストリーム構成でターゲットのヘルスチェックを実行ます。応答性があるか どうかに基づいて、健康か不健康かをマークします。 リングバランサーは、健康なターゲットにのみトラフィックをルーティングします。

Kongは2種類のヘルスチェックをサポートしており、個別に使用したり、 以下のように組み合わせて使用したりすることができます。

  • アクティブチェック では、ターゲット内の特定の HTTP または HTTPS エンドポイントが定期的にリクエストされ、そのレスポンスに基づいてターゲットの健全性が判断されます。

  • パッシブチェック （ サーキットブレーカーとも呼ばれます ）では、Kongはプロキシされている進行中のトラフィックを分析し、リクエストに対するターゲットの動作に基づいてターゲットの正常性を判断します。

    注: この機能はハイブリッドモードではサポートされていません。

正常（healthy）および異常（unhealthy）の定義

ターゲット

ヘルスチェック機能の目的は、 特定のKongノード に対して、ターゲットを動的に正常または異常としてマークすることです。クラスタ全体でのヘルス情報の同期は行われず、各Kongノードがターゲットのヘルスを個別に判断します。これは、ある時点で1つのKongノードがターゲットに正常に接続でき、別のノードがそれに到達できない可能性があるため、望ましいことです。最初のノードはそれを正常とみなし、2番目のノードは異常とマークして、アップストリームのほかのターゲットへのトラフィックのルーティングを開始します。

（アクティブヘルスチェックでの）アクティブなプローブまたは（パッシブ ヘルスチェックでの）プロキシされたリクエストのいずれかが、ターゲットが健康か不健康かを 判断するのに使われるデータを生成します。リクエストはTCPエラー、 タイムアウト、またはHTTPステータスコードを生成する可能性があります。この情報に 基づいて、ヘルスチェッカーは一連の内部カウンターを更新します。

  • 返されたステータスコードが「正常」として構成されたものである場合、ターゲットの「成功」カウンターが増やされ、他のカウンターはすべてクリアされます。
  • 接続に失敗した場合は、ターゲットの「TCP failures」カウンタが増加し、「Successes」カウンタがクリアされます。
  • タイムアウトした場合、ターゲットの「タイムアウト」カウンターが増加され、「成功」カウンターがクリアされます。
  • 返されたステータスコードが「異常」として設定されたものである場合、ターゲットの「HTTP失敗」カウンターが増加し、「成功」カウンターはクリアされます。

「TCP エラー」、「HTTP エラー」、または「タイムアウト」カウンターのいずれかが構成されたしきい値に達すると、ターゲットは異常としてマークされます。

「成功」カウンタが設定されたしきい値に達すると、ターゲットは健康であると マークされます。

「正常」または「異常」のHTTPステータスコードのリストと、これらの各カウンタの個別のしきい値は、アップストリームごとに構成できます。以下に、アップストリームエンティティの設定例を示し、ヘルスチェックの設定に使用できるさまざまなフィールドのデフォルト値を示します。各フィールドの説明は、 Admin APIリファレンスドキュメントに含まれています。

{
    "name": "service.v1.xyz",
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "threshold": 0
    },
    "slots": 10
}

アップストリームが異常な場合（利用可能な容量%が設定された値より少ない場合） しきい値を超えると、Kongは503 Service Unavailableで上流への リクエストに応答します。

注：

  1. ヘルスチェックは アクティブな ターゲットに対してのみ動作し、 Kong データベース内のターゲットの アクティブ なステータスを変更しません。
  2. 異常なターゲットはロードバランサーから削除されないため、ハッシュアルゴリズムを使用している場合、バランサーのレイアウトには影響しません（単にスキップされます）。
  3. DNSの注意事項とバランサーの注意事項はヘルスチェックにも適用されます。ターゲットにホスト名を使用する場合は、DNSサーバーが常に名前用の完全なIPアドレスセットを返すようにし、応答を制限しないようにします。 そうしない場合、ヘルスチェックが実行されないことがあります。

アップストリーム

個々のターゲットのヘルスチェック機能に加え、アップストリームには「ヘルス」という概念も持ち合わせます。 アップストリームのヘルスはそのターゲットの状態に基づいて決定されます。

アップストリームの健全性の設定はプロパティhealthchecks.thresholdを通じて行われます 。これは、アップストリームが正常であるとみなされるための最小ターゲット「重み」（容量）のパーセンテージです。

簡単な例を次に示します。

  • アップストリームがhealthchecks.threshold=55で設定されたと想定します。
  • ターゲットは5つあり、それぞれにweight=100があるため、リングバランサーの重みの合計は500になります。

障害が発生し始めると、最初のターゲットのサーキットブレーカーが作動します。現在は異常だと考えられています。これは、リングバランサーでは、容量の20％が異常になっていることを意味します（重み500のうち100）。これはまだしきい値は55を超えているため、残りのターゲットは失敗したターゲットのトラフィックを処理します。

2つ目の障害が発生すると、別のターゲットが失敗し、さらに100の重みが異常として失われます。これでリングバランサは容量の60%で動作するようになりましたが、それでも設定されたしきい値の範囲内です。

システムオーバーロードが原因で2つの障害が発生したと仮定した場合、残りの60％も全負荷に対処できなくなり、すぐに3つ目のノードに障害が発生し、正常な容量が40％に減少すると推定することができます。この時点で、アップストリームの健全性は閾値を下回り、それ自体が不健全としてマークされます。

異常な状態になると、アップストリームはエラーのみを返します。これにより、ターゲット/サービスは、発生していた連鎖的な障害から回復します。

ターゲットが回復し始め、アップストリームの利用可能な容量が再びしきい値を超えると、リングバランサーのヘルスステータスは自動的に更新されます。

ヘルスチェックの種類

アクティブヘルスチェック

アクティブヘルスチェックは、その名の通り、ターゲットの健康状態を積極的にプローブします。アップストリームエンティティでアクティブなヘルスチェックが有効になっている場合、Kong はアップストリームの各ターゲットで設定されたパスに定期的に HTTP または HTTPS リクエストを発行します。これにより、Kong はプローブの結果に基づいてバランサー内のターゲットを自動的に有効または無効にできます。

アクティブヘルスチェックの周期は、ターゲットが健康か不健康かで 個別に設定できます。どちらかのinterval値がゼロに 設定されている場合、対応するシナリオでのチェックは無効になります。 両方がゼロの場合、アクティブヘルスチェックは完全に無効になります。

注： アクティブヘルスチェックは、HTTP/HTTPSターゲットのみをサポートします。プロトコル属性がtcpまたはTLSに設定されているサービスに割り当てられたアップストリームには適用されません。

パッシブヘルスチェック（サーキットブレーカー）

注: この機能はハイブリッドモードではサポートされていません。

パッシブヘルスチェックは、サーキットブレーカーとも呼ばれ、Kong（HTTP/HTTPS/TCP）によってプロキシされているリクエストに基づいて実行されるチェックであり、追加のトラフィックは生成されません。ターゲットが応答しない場合、パッシブヘルスチェッカーはそれを検出し、ターゲットを異常としてマークします。リングバランサーはこのターゲットをスキップし始めるため、これ以上トラフィックはルーティングされません。

ターゲットの問題が解決され、トラフィックを再び受け入れ準備が整うと、Kong管理者はAdmin APIエンドポイントを介して、ターゲットを再度有効にする必要があることをヘルスチェッカーに手動で通知できます。

curl -i -X PUT http://localhost:8001/upstreams/my_upstream/targets/10.1.2.3:1234/healthy

応答：

HTTP/1.1 204 No Content

このコマンドはクラスタ全体のメッセージをブロードキャストするため、「正常な」 ステータスがKongクラスタ全体に伝達されます。これにより、Kongノードは、Kongノードのすべてのワーカーで実行されているヘルスチェッカーのヘルスカウンターをリセットし、リングバランサーがトラフィックをターゲットに再びルーティングできるようにします。

パッシブヘルスチェックには余分なトラフィックを生成しないという利点がありますが、ターゲットを自動的に再度「正常」としてマークすることはできません。つまり、「回路が壊れている」ため、システム管理者がターゲットを再度有効にする必要があります。

長所と短所のまとめ

  • アクティブヘルスチェックは、リングバランサーのターゲットが正常になり次第、自動的に再有効化します。パッシブヘルスチェックはできません。
  • パッシブヘルスチェックでは、ターゲットへの追加トラフィックは発生しません。アクティブヘルスチェックでは発生します。
  • アクティブヘルスチェッカーは、ターゲット内に信頼できるステータスレスポンスのある 既知のURLを要求します。これはプローブのエンドポイントとして構成するためです（"/"のように シンプルなものとなる場合があります）。パッシブヘルスチェックは、このような設定は要求しません。
  • アクティブヘルスチェックのカスタムプローブエンドポイントを提供すると、アプリケーションは自己のヘルスメトリクスを決定し、Kongによって消費されるステータスコードを生成します。ターゲットがパッシブヘルスチェッカーには正常に見えるトラフィックを処理した場合でも、アクティブプローブには障害ステータスとして応答することができ、基本的に新しいトラフィックを受け取ることから解放されるようリクエストします。

2つのモードを組み合わせることが可能です。たとえば、 パッシブヘルスチェックを有効にして、ターゲットの状態をそのトラフィックのみに基づいて監視し、 ターゲットが異常であるときのみアクティブヘルスチェックを使用すると、 ターゲットを自動的に再度有効化できます。

ヘルスチェックの有効化と無効化

アクティブヘルスチェックを有効化

アクティブヘルスチェックを有効にするには、アップストリームオブジェクト構成のhealthchecks.activeで構成項目を指定する必要があります。 ターゲットと結果的に得られる情報の解釈方法に関するプローブをKongが定期的に実行できるように、必要な情報を指定する必要があります。

healthchecks.active.typeフィールドを、HTTPまたはHTTPSプローブを 実行するか（"http"または"https"に設定します）、単に 指定されたホストとポートへの接続が成功したかをテストする（"tcp"に 設定します）かで指定できます。

プローブの設定には、以下を指定する必要があります。

  • healthchecks.active.http_path - HTTP GETリクエストをターゲットに発行する場合に使用するパス。デフォルト値は"/"です。
  • healthchecks.active.timeout - プローブのHTTP GETリクエストの接続タイムアウト制限。デフォルト値は1秒です。
  • healthchecks.active.concurrency - アクティブヘルスチェックで同時にチェックするターゲットの数。

また、プローブを実行する場合の間隔にには正の値を指定する必要があります。

  • healthchecks.active.healthy.interval - 正常なターゲットのアクティブヘルスチェックの間隔（秒単位）。値がゼロの場合、正常なターゲットに対してアクティブプローブが実行されないことを示します。
  • healthchecks.active.unhealthy.interval - 正常でないターゲットのアクティブヘルスチェックの間隔（秒単位）。値がゼロの場合、正常でないターゲットのアクティブプローブが実行されるべきでないことを示します。

これにより、アクティブヘルスチェックの動作、正常（healthy）もしくは異常（unhealthy）なターゲットのプローブを、等間隔で実行するか、一方をもう一方より頻繁に実行するかどうかを調整できます。

HTTPSヘルスチェックを使用している場合は、以下のフィールドも指定できます。

  • healthchecks.active.https_verify_certificate - HTTPS を使用してアクティブなヘルスチェックを実行する際に、リモートホストのSSL証明書の有効性を確認するかどうか。
  • healthchecks.active.https_sni - HTTPSを使用したアクティブヘルスチェックの実行時に、SNI（Server Name Identification）として使用するホスト名。 これは、ターゲットがIPを使用して構成されている場合に特に役立ち、ターゲットホストの証明書を適切なSNIで検証できます。

TLS検証が失敗すると「TCP失敗」カウンタが増加し、プローブがHTTPまたはHTTPS経由で実行されたかにかかわらず、「HTTP失敗」はHTTPステータスコードのみを参照することにご留意ください。

最後に、Kongがプローブを解釈する方法を構成するために、ヘルスカウンターに多様なしきい値を設定して、到達するとステータス変更がトリガーされるようにする必要があります。 カウンターのしきい値フィールドは以下のとおりです。

  • healthchecks.active.healthy.successes-アクティブプローブでの成功数 (healthchecks.active.healthy.http_statuses で定義済)は ターゲットの正常と見なされます。
  • healthchecks.active.unhealthy.tcp_failures- TCP失敗の数 またはアクティブプローブでのTLS検証の失敗は、ターゲットが不健康であるとみなされます。
  • healthchecks.active.unhealthy.timeouts - ターゲットが正常でないと見なすためのアクティブプローブのタイムアウト数。
  • healthchecks.active.unhealthy.http_failures - ターゲットが異常であるとみなされるアクティブプローブでのHTTP失敗回数（ healthchecks.active.unhealthy.http_statusesで定義）。

パッシブヘルスチェックの有効化

注: この機能はハイブリッドモードではサポートされていません。

パッシブヘルスチェックは、ターゲットから流れる進行中のトラフィックを解釈して機能するため、プローブは機能しません。つまり、パッシブチェックを有効にするには、そのカウンターしきい値を構成するだけで済みます。

  • healthchecks.passive.healthy.successes - パッシブヘルスチェックで観察された、ターゲットを正常と見なすプロキシされたトラフィック（healthchecks.passive.healthy.http_statuses で定義）の成功数。パッシブチェックを有効にして、正常なトラフィックが異常なトラフィックのカウンターをリセットする場合は、これを正の値にする必要があります。
  • healthchecks.passive.unhealthy.tcp_failures - パッシブヘルスチェックで観測された、ターゲットを異常とみなすプロキシされたトラフィックのTCP失敗の数。
  • healthchecks.passive.unhealthy.timeouts - パッシブヘルスチェックで観測された、 ターゲットを異常とみなすプロキシされたトラフィックのタイムアウトの数。
  • healthchecks.passive.unhealthy.http_failures - パッシブヘルスチェックで観察された、ターゲットを異常と見なすプロキシされたトラフィック（healthchecks.passive.unhealthy.http_statuses で定義）の HTTP エラーの数。

ヘルスチェックの無効化

healthchecks構成で指定されたすべてのカウンタ閾値と間隔で、値をゼロに設定するとフィールドが表現する機能が無効になります。プローブの間隔をゼロに設定すると、プローブは無効になります。同様に、特定のタイプのチェックを無効にするには、そのカウンタ閾値をゼロに設定します。たとえば、タイムアウトを考慮せずにヘルスチェックを実行するには、両方のtimeoutsフィールド（アクティブとパッシブのチェック）をゼロに設定できます。こうすることで、ヘルスチェッカーの動作を微調整できます。

要約すると、アップストリームのアクティブヘルスチェックを完全に無効にするには、healthchecks.active.healthy.intervalとhealthchecks.active.unhealthy.intervalの両方を0に設定する必要があります。

パッシブヘルスチェックを完全に無効にするには、 healthchecks.passive下のさまざまなカウンターのしきい値をゼロに設定する必要があります。

healthchecksすべてのカウンタのしきい値と間隔はすべてデフォルトではゼロです。つまり、新しく作成されたアップストリームではヘルスチェックはデフォルトで完全に無効になっています。