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;
}

ディレクティブ

構文: upstream name { ... }
デフォルト: -
コンテキスト: stream

サーバのグループを定義します。サーバは異なるポートで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つの接続。サーバとの通信時にエラーが起きた場合、接続は次のサーバへ送られます。全ての機能しているサーバが試されるまでこれが行われます。全てのサーバへの通信が失敗すると、接続は閉じられるでしょう。

構文: server address [parameters];
デフォルト: -
コンテキスト: upstream

サーバの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.comserver1.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_timeoutslow_startパラメータは無視され、そのようなサーバは利用不可だとは見なされないでしょう。

構文: zone name [size];
デフォルト: -
コンテキスト: upstream

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

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

構文: state file;
デフォルト: -
コンテキスト: upstream

このディレクティブはバージョン1.9.7から導入されました。

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

例:

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 の間の変更は失われるかも知れません。

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

構文: hash key [consistent];
デフォルト: -
コンテキスト: upstream

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

hash $remote_addr;

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

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

構文: least_conn;
デフォルト: -
コンテキスト: upstream

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

構文: least_time connect | first_byte | last_byte [inflight];
デフォルト: -
コンテキスト: upstream

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

connect パラメータが指定された場合は、upstreamサーバへの接続時間が使われます。first_byte パラメータが指定された場合は、データの最初のバイトを受け取るまでの時間が使われます。last_byte が指定された場合は、データの最後のバイトを受け取るまでの時間が使われます。If the inflight parameter is specified (1.11.6), incomplete connections are also taken into account.

Prior to version 1.11.6, incomplete connections were taken into account by default.

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

埋め込み変数

The ngx_stream_upstream_module module supports the following embedded variables:

$upstream_addr
keeps the IP address and port, or the path to the UNIX-domain socket of the upstream server (1.11.4). If several servers were contacted during proxying, their addresses are separated by commas, e.g. “192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”.
$upstream_bytes_sent
number of bytes sent to an upstream server (1.11.4). Values from several connections are separated by commas like addresses in the $upstream_addr variable.
$upstream_bytes_received
upstreamサーバから受け取ったバイト数 (1.11.4)。Values from several connections are separated by commas like addresses in the $upstream_addr variable.
$upstream_connect_time
time to connect to the upstream server (1.11.4); the time is kept in seconds with millisecond resolution. Times of several connections are separated by commas like addresses in the $upstream_addr variable.
$upstream_first_byte_time
time to receive the first byte of data (1.11.4); the time is kept in seconds with millisecond resolution. Times of several connections are separated by commas like addresses in the $upstream_addr variable.
$upstream_session_time
session duration in seconds with millisecond resolution (1.11.4). Times of several connections are separated by commas like addresses in the $upstream_addr variable.

TOP
inserted by FC2 system