ngx_stream_upstream_module モジュール

ngx_stream_upstream_moduleモジュール(1.9.0)は proxy_passディレクティブによって参照されるサーバグループを定義するために使われます。

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

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

server {
    listen 12346;
    proxy_pass backend;
}

周期的なhealthチェック を持つ動的な構成可能なグループは商用許可の一部として利用可能です:

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 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 backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

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

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

サーバのグループを定義します。サーバは異なるポートでlistenすることができます。更に、サーバのlistenしているTCPとUNIXドメインソケットを混ぜることができます。

例:

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

デフォルトでは、重み付けのラウンドロビン バランシング メソッドを使って接続はサーバの間にばらまかされます。上の例では、7つのリクエストが以下のように分配されるでしょう: 5つの接続は backend1.example.com:12345へ、2つめと3つめのサーバへ1つの接続。サーバとの通信時にエラーが起きた場合、接続は次のサーバへ送られます。全ての機能しているサーバが試されるまでこれが行われます。全てのサーバへの通信が失敗すると、接続は閉じられるでしょう。

サーバのaddressとその他の parameters を定義します。アドレスはドメイン名またはIPアドレス、必須のポート番号、あるいは"unix:"プリフィックスの後で指定されるUNIXドメインソケットで指定されます。複数のIPアドレスに解決されるドメイン名は一度に複数のサーバを定義します。

次のパラメータを定義することができます:

weight=number

サーバの重み付けを設定します。デフォルトは1。

max_conns=number

プロキシされるサーバへの同時接続の最大numberを制限します(1.11.5)。デフォルトの値は0です。制限が無いことを意味します。サーバグループが 共有メモリ内に無い場合は、その制限は各ワーカープロセスごとに動作します。

バージョン 1.11.5以前では、このパラメータは商用許可の一部として利用可能でした。

max_fails=number

fail_timeout パラメータによって設定された期間中にサーバが利用できないと見なすためのfail_timeoutパラメータによって設定された期間に起こるはずのサーバとの通信で失敗する試行の回数を設定します。デフォルトでは、不成功の数は1に設定されます。0の値は試行のカウントを無効にします。これで、失敗した試行はサーバへの接続の確立時にエラーあるいはタイムアウトします。

fail_timeout=time

sets

• サーバが利用不可能だと見なされるために必要な、指定回数のサーバとの通信の失敗の試行が起こる期間
• その間サーバは利用不可能とみなされるでしょう。

デフォルトでは、パラメータは10秒に設定されます。

バックアップ

サーバをバックアップサーバとして印をつけます。バックアップサーバへの接続はプライマリサーバが利用できない場合に渡されるでしょう。

パラメータはhash、randomロードバランシング メソッドと一緒に使うことはできません。

down

サーバを永久に利用できないとして印を付けます。

更に、次のパラメータが商用許可の一部として利用可能です:

resolve

ドメイン名に対応するIPアドレスの変更を監視し、nginxの再起動の必要無しにupstream設定の変更を自動的に行います。サーバグループは共有メモリにある必要があります。

このパラメータを機能させるには、resolverディレクティブをstreamブロック、または対応するupstreamブロックで指定する必要があります。

service=name

DNS のSRV レコードの解決を有効にし、サービス nameを設定します (1.9.13)。このパラメータが動作するには、サーバのresolve パラメータを指定し、ポート番号無しのホスト名を指定する必要があります。

サービス名がドット (“.”)を含まない場合、RFC準拠名が作られ、TCPプロトコルがサービスの後に追加されます。例えば、_http._tcp.backend.example.com SRV レコードを調べるには、ディレクティブを指定する必要があります。

server backend.example.com service=http resolve;

サービス名が1つ以上のドットを含む場合、サービスのプリフィックスとサーバー名を結合することで名前が作られます。例えば、_http._tcp.backend.example.com とserver1.backend.example.com SRV レコードを調べるには、以下のディレクティブを指定する必要があります:

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

最優先 SRV レコード (同じ最小の優先度値のレコード)はプライマリサーバとして解決され、残りのSRVレコードはバックアップサーバとして解決されます。サーバにbackup パラメータが指定された場合は、最優先SRVレコードはバックアップサーバとして解決され、残りのSRVレコードは無視されます。

slow_start=time

健康では無いサーバがhealthyになる時、またはサーバがunavailableと見なされてから一定期間後に利用可能となる時に、サーバの重み付けが0から通常の値になるまでの時間。デフォルト値は0です。つまりslowスタートは無効です。

パラメータはhash、randomロードバランシング メソッドと一緒に使うことはできません。

グループにサーバが一つだけの場合、max_fails, fail_timeout と slow_startパラメータは無視され、そのようなサーバは利用不可だとは見なされないでしょう。

グループの設定とworkerプロセス間で共有されるランタイムステートを保持する共有メモリ領域のnameと size を定義します。幾つかのグループは同じゾーンを共有するかも知れません。この場合、sizeの指定は一度だけで十分です。

さらに、商用サブスクリプションの一部として、そのようなグループは、グループのメンバーの変更または特定のサーバの設定の変更をnginxの再起動無しに行うことができます。設定はAPI モジュールを使ってアクセス可能です (1.13.3)。

バージョン 1.13.3以前では、設定はupstream_confによって処理される特別なlocationを使ってのみアクセス可能でした。

動的に設定可能なグループの状態を保持する ファイル を指定します。

例:

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

状態は現在のところサーバのパラメータとサーバのリストに制限されています。そのファイルは、設定をパースする時と、upstreamの設定が変更される度に更新されます。ファイルの内容を直接変更することは避けなければなりません。ディレクティブは server ディレクティブと一緒に使うことはできません。

configuration reload あるいはbinary upgrade の間の変更は失われるかも知れません。

このディレクティブは商用許可の一部として利用可能です。

クライアント-サーバのマッピングがハッシュ化されたkey 値に基づいているサーバグループのためのロードバランス設定を指定します。keyにはテキスト、変数、それらの組み合わせを含めることができます (1.11.2)。利用例:

hash $remote_addr;

グループからサーバを追加または削除することは、ほとんどのキーを異なるサーバに再マッピングすることになることに注意してください。メソッドはCache::Memcached Perlライブラリと互換性があります。

consistentパラメータが指定される場合、ketama consistent ハッシュメソッドが代わりに使われるでしょう。このメソッドはグループからサーバを追加または削除する時に、ほんの少しのキーだけが異なるサーバに再マップされることを保証します。これにより、キャッシュサーバのキャッシュヒットレシオの高さを達成できることができます。このメソッドはketama_points パラメータを160に設定したCache::Memcached::Fast Perl ライブラリと互換性があります。

接続がサーバの重み付けを考慮してもっともアクティブな接続の数が少ないサーバに渡されるロードバランスメソッドをグループが使うように指定します。そのようなサーバがいくつかある場合は、重み付けのラウンドロビンバランスメソッドを使って順番に試されます。

接続がサーバの重み付けを考慮して最も平均応答タイムが小さく最もアクティブな接続の数が少ないサーバに渡されるロードバランスメソッドをグループが使うように指定します。そのようなサーバがいくつかある場合は、重み付けのラウンドロビンバランスメソッドを使って順番に試されます。

connect パラメータが指定された場合は、upstreamサーバへのconnect時間が使われます。first_byte パラメータが指定された場合は、データの最初のバイトを受け取るまでの時間が使われます。last_byte が指定された場合は、データの最後のバイトを受け取るまでの時間が使われます。inflight パラメータが指定された場合 (1.11.6)、不完全な接続も考慮に入れられます。

バージョン 1.11.6より前では、不完全な接続はデフォルトで考慮に入れられていました。

このディレクティブは商用許可の一部として利用可能です。

サーバの重み付けを考慮して、接続がランダムに選択されたサーバに渡されるロードバランシング メソッドを使うべきグループを指定します。

任意のtwo パラメータはnginxにランダムに two サーバを選択するように指示し、指定されたmethodを使ってサーバを選択します。デフォルトのメソッドはアクティブな接続が最も少ないサーバに接続を渡すleast_connです。

least_timeメソッドは、平均時間が最小で、アクティブな接続の数が最も少ないサーバに接続を渡します。least_time=connect パラメータが指定された場合は、upstreamサーバへのconnect時間が使われます。least_time=first_byte パラメータが指定された場合は、データの最初のバイトを受け取るまでの時間が使われます。least_time=last_byte が指定された場合は、データの最後のバイトを受け取るまでの時間が使われます。

least_timeメソッドは、商用サブスクリプションの一部として利用できます。

upstreamサーバの名前をアドレス解決するために使われるネームサーバを設定します。例えば:

resolver 127.0.0.1 [::1]:5353;

アドレスはドメイン名またはIPアドレス、オプションとしてポートが指定可能です。ポートが指定された場合は、ポート53が使われるでしょう。ラウンドロビンの形式で、ネームサーバが照合されます。

デフォルトでは、nginxは名前解決の時にIPv4とIPv6アドレスの両方を調べるでしょう。IPv6アドレスの調査が望ましいものではない場合、ipv6=off パラメータを指定することができます。

デフォルトでは、nginxのキャッシュは 応答のTTL値を使って返答します。オプションの valid パラメータはそれを上書くことができます:

resolver 127.0.0.1 [::1]:5353 valid=30s;

DNSスプーフィングを避けるために、適切に安全な信頼できるローカルネットワーク内のDNSサーバを設定することをお勧めします。

オプションのstatus_zoneパラメータは、指定されたゾーンの要求と応答のDNSサーバ統計のコレクションを有効にします。

このディレクティブは商用許可の一部として利用可能です。

resolver_timeout 30s;

名前解決のタイムアウトを設定します。例えば:

resolver_timeout 5s;

このディレクティブは商用許可の一部として利用可能です。

ngx_stream_upstream_moduleモジュールは次の埋め込み変数をサポートします:

$upstream_addr

upstreamサーバのIPアドレスとポート、あるいはUNIXドメインソケットのパスを保持します (1.11.4)。いくつかのサーバがプロキシ中に接点を持つ場合は、それらのアドレスがカンマで区切られます。例えば、"192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock"。もしサーバを選択することができない場合、変数はサーバグループの名前を保持するでしょう。

$upstream_bytes_received

upstreamサーバから受け取ったバイト数 (1.11.4)。複数の接続の値は、$upstream_addr 変数のアドレスと同じようにカンマで区切られます。

$upstream_bytes_sent

upstreamサーバへ送信するバイト数 (1.11.4)。複数の接続の値は、$upstream_addr 変数のアドレスと同じようにカンマで区切られます。

$upstream_connect_time

upstreamサーバへ接続するまでの時間 (1.11.4); 時間はミリ秒の精度の秒数で保持されます。複数の接続時間は$upstream_addr 変数のアドレスと同じようにカンマで区切られます。

$upstream_first_byte_time

データの最初のバイトを受け取るまでの時間 (1.11.4); 時間はミリ秒の精度の秒数で保持されます。複数の接続時間は$upstream_addr 変数のアドレスと同じようにカンマで区切られます。

$upstream_session_time

ミリ秒の精度のセッションの持続秒数 (1.11.4)。複数の接続時間は$upstream_addr 変数のアドレスと同じようにカンマで区切られます。