ngx_stream_upstream_module モジュール

設定例 ディレクティブ      upstream      server      zone      state      hash      least_conn      least_time 組み込み変数

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秒に設定されます。

バックアップ

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

down

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

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

resolve

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

このパラメータが動作するには、streamブロックのresolverディレクティブが指定されていなければなりません。例:

stream {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com:12345 resolve;
    }
}

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 ロードバランシング メソッドと一緒に使うことはできません。

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

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

さらに、商用サブスクリプションの一部として、そのようなグループは、グループのメンバーの変更または特定のサーバの設定の変更をnginxの再起動無しに行うことができます。設定は、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サーバへの接続時間が使われます。first_byte パラメータが指定された場合は、データの最初のバイトを受け取るまでの時間が使われます。last_byte が指定された場合は、データの最後のバイトを受け取るまでの時間が使われます。inflight パラメータが指定された場合 (1.11.6)、不完全な接続も考慮に入れられます。

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

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

埋め込み変数

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_sent

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

$upstream_bytes_received

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 変数のアドレスと同じようにカンマで区切られます。