ngx_http_upstream_hc_module モジュール
設定例 ディレクティブ health_check match |
ngx_http_upstream_hc_module
モジュールは、取り囲んでいるlocation内で参照されるgroup内のサーバの定期的なヘルスチェックを有効にすることができます。サーバグループは共有メモリ内にある必要があります。
ヘルスチェックが失敗した場合、サーバは健康ではないと見なされるでしょう。いくつかのヘルスチェックがサーバの同じグループに定義されている場合、いずれかのチェックの一つの失敗により対応するサーバが健康では無いと見なされるでしょう。クライアントのリクエストは健康ではないサーバと “調査中” 状態のサーバへ渡されません。
ヘルスチェックで使われる場合に、ほとんどの変数が空の値を持つことに注意してください。
このモジュールは商用許可の一部として利用可能です。
設定例
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 [ |
---|---|
デフォルト: | - |
コンテキスト: |
場所 |
取り囲んでいるlocation内で参照されるgroup の中でサーバの定期的なヘルスチェックを有効にします。
次の任意のパラメータがサポートされます:
-
interval
=time
- 二つの連続するヘルスチェックの間の時間を設定します。デフォルトは5秒です。
-
jitter
=time
- 各ヘルスチェックがランダムに遅れる時間の範囲を設定します。デフォルトでは遅れはありません。
-
fails
=number
- 特定のサーバがヘルスチェックに連続して失敗して健康では無いと見なされる数を設定します。デフォルトは1です。
-
passes
=number
- 特定のサーバがヘルスチェックに連続して成功して健康であると見なされる数を設定します。デフォルトは1です。
-
uri
=uri
-
ヘルスチェックのリクエストで使われるURIを定義します。デフォルトは"<
/
"です。 -
mandatory
[persistent
] -
最初のヘルスチェックが完了するまでのサーバについての初回の"checking"状態を設定します (1.11.7)。クライアント リクエストは"調査中"状態のサーバへ渡されません。パラメータが指定されない場合、サーバは最初は健康であると見なされるでしょう。
persistent
パラメータ (1.19.7)は、サーバーがリロード前に健康であると見なされた場合、リロード後のサーバの初期の“up”状態を設定します。 -
match
=name
-
応答がヘルスチェックにパスするために必要なテストを順番に設定する
match
ブロックを指定します。デフォルトでは、応答はステータスコード 2xx あるいは 3xx でなければなりません。 -
port
=number
- ヘルスチェックを実行するためにサーバへ接続する時に使われるポートを定義します(1.9.7)。デフォルトでは、server ポートに等しいです。
-
type
=grpc
[grpc_service
=name
] [grpc_status
=code
] -
オプションの
grpc_service
パラメータで指定されたgRPCサーバまたは特定のgRPCサービスのhealth checksを有効にします。サーバがgRPC Health Checking Protocolをサポートしない場合は、オプションのgrpc_status
パラメータを使って、健康だと扱われるゼロ以外のgRPC status (例えば、ステータスコード“12
” / “UNIMPLEMENTED
”)を指定できます。health_check mandatory type=grpc grpc_status=12;
type
=grpc
パラメータは他の全てのディレクティブパラメータの後に指定する必要があり、grpc_service
とgrpc_status
はtype
=grpc
の後に指定する必要があります。パラメータは、uri
またはmatch
パラメータと互換性はありません。 -
keepalive_time
=time
- ヘルスチェックにkeepalive接続を有効にし、1つのkeepalive接続でリクエストを処理できる時間を指定します (1.21.7)。デフォルトでは、keepalive接続は無効です。
構文: |
match |
---|---|
デフォルト: | - |
コンテキスト: |
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
...;
- 指定された全ての変数は空dではなく、“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; }