ngx_stream_upstream_module モジュール

設定例
ディレクティブ
     upstream
     server
     zone
     state
     hash
     least_conn
     least_time
     health_check
     health_check_timeout
     match
Embedded Variables

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

動的なグループの構成は商用許可の一部として利用可能です。

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;
デフォルト: -
コンテキスト: upstream

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

connect パラメータが指定された場合は、upstreamサーバへの接続時間が使われます。first_byte パラメータが指定された場合は、データの最初のバイトを受け取るまでの時間が使われます。last_byte が指定された場合は、データの最後のバイトを受け取るまでの時間が使われます。

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

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

group内のサーバの健康状態を定期的に有効にします。

次の任意のパラメータがサポートされます:

interval=time
二つの連続するヘルスチェックの間の時間を設定します。デフォルトは5秒です;
jitter=time
各ヘルスチェックがランダムに遅れる時間の範囲を設定します。デフォルトでは遅れはありません;
fails=number
特定のサーバがヘルスチェックに連続して失敗して健康では無いと見なされる数を設定します。デフォルトは1です;
passes=number
特定のサーバがヘルスチェックに連続して成功して健康であると見なされる数を設定します。デフォルトは1です;
match=name
応答がヘルスチェックにパスするために必要なテストを順番に設定するmatchブロックを指定します。デフォルトでは、サーバへTCP接続を確立する機能のみが調べられます;
port=number
ヘルスチェックを実行するためにサーバへ接続する時に使われるポートを定義します(1.9.7); デフォルトでは、server ポートと同じです;
udp
デフォルトのTCPプロトコルの変わりにヘルスチェックのために使われるべきUDP プロトコルを指定します (1.9.13); sendexpectパラメータと一緒にmatchブロックが必要とされます。

例えば:

server {
    proxy_pass backend;
    health_check;
}

5秒毎にbackend グループ内の各サーバへのTCP接続を確立できるかどうかを調べるでしょう。接続が確立できなかった場合、健康チェックは失敗し、サーバは健康ではないと見なされるでしょう。クライアント接続は健康ではないサーバへ渡されないでしょう。

健康チェックはサーバから取得されるデータのテストをするよう設定することもできます。テストは、matchディレクティブを使って個々に設定することができ、match パラメータの中で参照されます。

サーバグループは共有メモリにある必要があります。

いくつかのヘルスチェックがサーバの同じグループに定義されている場合、いずれかのチェックの一つの失敗により対応するサーバが健康では無いと見なされるでしょう。

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

構文: health_check_timeout timeout;
デフォルト:
health_check_timeout 5s;
コンテキスト: stream, server

健康チェックのためのproxy_timeout値を上書きします。

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

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

ヘルスチェックへのサーバ応答の検証に使われる名前付きのテストセットを定義します。

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

send string;
string をサーバに送信します;
expect string | ~ regex;
文字列(1.9.12)あるいは、データから取得したデータが一致しなければならない正規表現。正規表現は先行する"~*"修飾子(大文字小文字を区別しないマッチング)、または"~"修飾子(大文字小文字を区別するマッチング)によって指定されます。

Both send and expect parameters can contain hexadecimal literals with the prefix “\x” followed by two hex digits, for example, “\x80” (1.9.12).

以下の場合、健康チェックが通ります:

例:

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}

サーバから取得されたデータの最初のproxy_buffer_size バイトだけがテストされます。

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

埋め込み変数

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