ngx_stream_upstream_hc_module モジュール

ngx_stream_upstream_hc_module モジュール（1.9.0）を使用すると、グループ内のサーバーの定期的なヘルスチェックを有効にできます。サーバーグループは、共有メモリに存在する必要があります。

ヘルスチェックが失敗した場合、サーバーは異常とみなされます。同じサーバーグループに対して複数のヘルスチェックが定義されている場合、いずれかのチェックで1回失敗すると、対応するサーバーは異常とみなされます。クライアント接続は、異常なサーバーと「チェック中」状態のサーバーには渡されません。

このモジュールは、当社の商用サブスクリプションの一部として利用できます。

upstream tcp {
    zone upstream_tcp 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen     12346;
    proxy_pass tcp;
    health_check;
}

この設定では、nginx は 5 秒ごとに tcp グループ内の各サーバーへの TCP 接続を確立できるかどうかをチェックします。サーバーへの接続を確立できない場合、ヘルスチェックは失敗し、サーバーは異常とみなされます。

UDPプロトコル用にヘルスチェックを設定できます。

upstream dns_upstream {

    zone   dns_zone 64k;

    server dns1.example.com:53;
    server dns2.example.com:53;
    server dns3.example.com:53;
}

server {
    listen       53 udp;
    proxy_pass   dns_upstream;
    health_check udp;
}

この場合、送信された文字列「nginx health check」への応答として、ICMP「Destination Unreachable」メッセージがないことが期待されます。

サーバーから取得したデータをテストするようにヘルスチェックを設定することもできます。テストは、match ディレクティブを使用して個別に構成され、health_check ディレクティブの match パラメータで参照されます。

グループ内のサーバーの定期的なヘルスチェックを有効にします。

以下のオプションのパラメータがサポートされています

interval=time

2 回の連続したヘルスチェックの間隔を秒単位で設定します。デフォルトは 5 秒です。

jitter=time

各ヘルスチェックがランダムに遅延する時間を設定します。デフォルトでは遅延はありません。

fails=number

特定のサーバーのヘルスチェックが連続して失敗した回数を設定します。この回数を超えると、サーバーは異常とみなされます。デフォルトは 1 です。

passes=number

特定のサーバーのヘルスチェックが連続して成功した回数を設定します。この回数を超えると、サーバーは正常とみなされます。デフォルトは 1 です。

mandatory [persistent]

最初のヘルスチェックが完了するまで、サーバーの初期状態を「チェック中」に設定します（1.11.7）。クライアント接続は、「チェック中」状態のサーバーには渡されません。パラメータが指定されていない場合、サーバーは初期状態では正常とみなされます。

persistent パラメータ（1.21.1）は、サーバーがリロード前に正常とみなされていた場合、リロード後のサーバーの初期状態を「up」に設定します。

match=name

ヘルスチェックが成功するために、正常な接続が通過する必要があるテストを構成する match ブロックを指定します。デフォルトでは、TCP の場合、サーバーとの TCP 接続を確立できるかどうかのみがチェックされます。UDP の場合、送信された文字列「nginx health check」への応答として、ICMP「Destination Unreachable」メッセージがないことが期待されます。

バージョン 1.11.7 より前では、デフォルトで UDP ヘルスチェックには、send パラメータと expect パラメータを持つ match ブロックが必要でした。

port=number

ヘルスチェックを実行するためにサーバーに接続する際に使用するポートを定義します（1.9.7）。デフォルトでは、server ポートと同じです。

udp

デフォルトの TCP プロトコルの代わりに、ヘルスチェックに UDP プロトコルを使用する必要があることを指定します（1.9.13）。

health_check_timeout 5s;

ヘルスチェックの proxy_timeout 値を上書きします。

ヘルスチェックへのサーバー応答を検証するために使用される名前付きテストセットを定義します。

以下のパラメータを設定できます。

send string;

サーバーに string を送信します。

expect string | ~ regex;

サーバーから取得したデータが一致する必要があるリテラル文字列（1.9.12）または正規表現。正規表現は、先行する「~*」修飾子（大文字と小文字を区別しないマッチングの場合）、または「~」修飾子（大文字と小文字を区別するマッチングの場合）で指定します。

send パラメータと expect パラメータの両方に、接頭辞「\x」とそれに続く 2 桁の 16 進数（たとえば、「\x80」（1.9.12））を持つ 16 進数のリテラルを含めることができます。

ヘルスチェックは、以下の場合に合格となります。

• TCP 接続が正常に確立された。
• 指定されている場合、send パラメータからの string が送信された。
• 指定されている場合、サーバーから取得したデータが expect パラメータからの文字列または正規表現に一致した。
• 経過時間が health_check_timeout ディレクティブで指定された値を超えていない。

例

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}

サーバーから取得したデータの最初の proxy_buffer_size バイトのみが検査されます。