モジュール ngx_http_upstream_hc_module

設定例
ディレクティブ
     health_check
     match

ngx_http_upstream_hc_module モジュールを使用すると、周辺のロケーションで参照される グループ 内のサーバーの定期的なヘルスチェックを有効にできます。サーバーグループは 共有メモリ に存在する必要があります。

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

ヘルスチェックで使用すると、ほとんどの変数は空の値になることに注意してください。

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

設定例

upstream dynamic {
    zone upstream_dynamic 64k;

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

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

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

この設定では、nginx は 5 秒ごとに `backend` グループ内の各サーバーに “/” リクエストを送信します。通信エラーやタイムアウトが発生した場合、またはプロキシされたサーバーが 2xx または 3xx 以外のステータスコードで応答した場合、ヘルスチェックは失敗し、サーバーは異常と見なされます。

ヘルスチェックは、応答のステータスコード、特定のヘッダーフィールドとその値の存在、および本文の内容をテストするように設定できます。テストは、match ディレクティブを使用して個別に設定され、health_check ディレクティブの match パラメーターで参照されます。

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

この設定では、ヘルスチェックに合格するためには、ヘルスチェックリクエストへの応答が成功し、ステータス 200 であり、本文に “Welcome to nginx!” が含まれている必要があることを示しています。

ディレクティブ

構文 health_check [parameters];
デフォルト —
コンテキスト location

周辺のロケーションで参照される グループ 内のサーバーの定期的なヘルスチェックを有効にします。

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

interval=time
2 回の連続したヘルスチェックの間隔を、デフォルトでは 5 秒に設定します。
jitter=time
各ヘルスチェックがランダムに遅延する時間を設定します。デフォルトでは遅延はありません。
fails=number
特定のサーバーのヘルスチェックの連続失敗回数を設定し、この回数を超えるとサーバーは異常と見なされます。デフォルトは 1 です。
passes=number
特定のサーバーのヘルスチェックの連続成功回数を設定し、この回数を超えるとサーバーは正常と見なされます。デフォルトは 1 です。
uri=uri
ヘルスチェックリクエストで使用される URI を定義します。デフォルトは “/” です。
mandatory [persistent]

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

persistent パラメーター (1.19.7) は、リロード前にサーバーが正常と見なされていた場合、リロード後にサーバーの初期状態を「起動」に設定します。

match=name
ヘルスチェックを合格するために応答が満たす必要があるテストを設定する match ブロックを指定します。デフォルトでは、応答はステータスコード 2xx または 3xx である必要があります。
port=number
ヘルスチェックを実行するためにサーバーに接続する際に使用されるポートを定義します (1.9.7)。デフォルトでは、server ポートと同じです。
type=grpc [grpc_service=name] [grpc_status=code]
gRPC サーバーまたはオプションの grpc_service パラメーターで指定された特定の gRPC サービスの定期的な ヘルスチェック を有効にします (1.19.5)。サーバーが gRPC ヘルスチェックプロトコルをサポートしていない場合、オプションの grpc_status パラメーターを使用して、正常と見なされる非ゼロの gRPC ステータス (たとえば、ステータスコード “12” / “UNIMPLEMENTED”) を指定できます
health_check mandatory type=grpc grpc_status=12;
type=grpc パラメーターは、他のすべてのディレクティブパラメーターの後に指定する必要があり、grpc_service および grpc_status は type=grpc の後に続く必要があります。このパラメーターは、uri パラメーターまたは match パラメーターとは互換性がありません。
keepalive_time=time
ヘルスチェックの キープアライブ 接続を有効にし、1 つのキープアライブ接続を介してリクエストを処理できる時間を指定します (1.21.7)。デフォルトでは、キープアライブ接続は無効になっています。

構文 match name { ... }
デフォルト —
コンテキスト http

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

応答で次の項目をテストできます

status 200;
ステータスは 200
status ! 500;
ステータスは 500 ではない
status 200 204;
ステータスは 200 または 204
status ! 301 302;
ステータスは 301 でも 302 でもない
status 200-399;
ステータスは 200 から 399 の範囲内
status ! 400-599;
ステータスは 400 から 599 の範囲内ではない
status 301-303 307;
ステータスは 301、302、303、または 307 のいずれか

header Content-Type = text/html;
ヘッダーには、値 text/html を持つ “Content-Type” が含まれています
header Content-Type != text/html;
ヘッダーには、text/html 以外の値を持つ “Content-Type” が含まれています
header Connection ~ close;
ヘッダーには、正規表現 close に一致する値を持つ “Connection” が含まれています
header Connection !~ close;
ヘッダーには、正規表現 close に一致しない値を持つ “Connection” が含まれています
header Host;
ヘッダーには “Host” が含まれています
header ! X-Accel-Redirect;
ヘッダーに “X-Accel-Redirect” がありません

body ~ "Welcome to nginx!";
本文は正規表現 “Welcome to nginx!” に一致します
body !~ "Welcome to nginx!";
本文は正規表現 “Welcome to nginx!” に一致しません

require $variable ...;
指定されたすべての変数が空ではなく、かつ “0” と等しくありません (1.15.9)。

複数のテストが指定されている場合、応答がすべてのテストに一致する場合のみ一致します。

応答本文の最初の 256k のみが調べられます。

例

# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}


# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}


# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}


# status is 200 or 204
map $upstream_status $good_status {
    200 1;
    204 1;
}

match server_ok {
    require $good_status;
}