モジュール 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;
}

定期的なヘルスチェックを備えた動的に構成可能なグループは、当社の商用サブスクリプションの一部として提供されています。

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

サーバーのグループを定義します。サーバーは異なるポートでリスンできます。さらに、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に、1つの接続が2番目と3番目のサーバーそれぞれに送られます。サーバーとの通信中にエラーが発生した場合、接続は次のサーバーに渡され、動作しているすべてのサーバーを試行するまで繰り返されます。すべてのサーバーとの通信に失敗した場合、接続は閉じられます。

サーバーのaddressおよびその他のparametersを定義します。アドレスは、必須のポート付きのドメイン名またはIPアドレス、または「unix:」プレフィックスの後に指定されたUNIXドメインソケットパスとして指定できます。複数のIPアドレスに解決されるドメイン名は、同時に複数のサーバーを定義します。

次のパラメーターを定義できます。

weight=number

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

max_conns=number

プロキシサーバーへの同時接続の最大数numberを制限します (1.11.5)。デフォルト値はゼロで、制限はありません。サーバーグループが共有メモリに存在しない場合、制限はワーカープロセスごとに適用されます。

バージョン1.11.5より前は、このパラメーターは当社の商用サブスクリプションの一部として提供されていました。

max_fails=number

fail_timeoutパラメーターで設定された期間内に発生する、サーバーとの通信を試行する失敗回数を設定します。サーバーは、fail_timeoutパラメーターで設定された期間、利用できないと見なされます。デフォルトでは、失敗回数は1に設定されています。0値は試行の集計を無効にします。ここでは、失敗した試行とは、サーバーとの接続確立時のエラーまたはタイムアウトです。

fail_timeout=time

設定します。

• サーバーとの通信を試行する失敗回数が、サーバーを利用できないと見なす期間内に発生する必要がある時間。
• そして、サーバーを利用できないと見なされる期間。

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

backup

サーバーをバックアップサーバーとしてマークします。プライマリサーバーが利用できない場合、バックアップサーバーへの接続が渡されます。

このパラメーターは、hashとrandomのロードバランシング方式と共に使用することはできません。

down

サーバーを恒久的に利用できないものとしてマークします。

さらに、次のパラメーターは当社の商用サブスクリプションの一部として提供されています。

resolve

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

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

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

正常でないサーバーが正常になった場合、またはサーバーが利用できないと見なされた期間後に利用可能になった場合に、サーバーがその重みをゼロから公称値に回復するまでのtimeを設定します。デフォルト値はゼロで、スロースタートは無効になります。

このパラメーターは、hashとrandomのロードバランシング方式と共に使用することはできません。

グループにサーバーが1つしかない場合、max_fails、fail_timeout、slow_startパラメーターは無視され、そのようなサーバーは決して利用できないと見なされません。

ワーカープロセス間で共有されるグループの設定と実行時状態を保持する共有メモリゾーンのnameとsizeを定義します。複数のグループが同じゾーンを共有できます。この場合、sizeを1回だけ指定すれば十分です。

さらに、当社の商用サブスクリプションでは、nginxを再起動することなく、グループメンバーシップの変更や特定のサーバーの設定の変更が可能です。設定はAPIモジュール (1.13.3) を介してアクセスできます。

バージョン1.13.3より前は、設定はupstream_confによって処理される特別な場所を介してのみアクセスできました。

動的に構成可能なグループの状態を保持するfileを指定します。

例

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

現在、状態はパラメーターを含むサーバーのリストに制限されています。ファイルは設定の解析時に読み取られ、upstream設定が変更されるたびに更新されます。ファイルの内容を直接変更することは避けてください。このディレクティブは、serverディレクティブと共に使用することはできません。

設定の再読み込みまたはバイナリのアップグレード中に加えられた変更は失われる可能性があります。

このディレクティブは、当社の商用サブスクリプションの一部として提供されています。

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

hash $remote_addr;

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

consistentパラメーターを指定すると、代わりにketama一貫性のあるハッシュ方式が使用されます。この方式により、グループにサーバーを追加または削除しても、再マッピングされるキーはごくわずかになります。これにより、キャッシングサーバーのキャッシュヒット率を高めることができます。この方式は、ketama_pointsパラメーターが160に設定されたCache::Memcached::Fast Perlライブラリと互換性があります。

サーバーの重みを考慮して、アクティブな接続数が最も少ないサーバーに接続が渡されるロードバランシング方式を使用するグループを指定します。そのようなサーバーが複数ある場合、重み付けラウンドロビン方式を使用して順番に試行されます。

サーバーの重みを考慮して、平均時間が最も短く、アクティブな接続数が最も少ないサーバーに接続が渡されるロードバランシング方式を使用するグループを指定します。そのようなサーバーが複数ある場合、重み付けラウンドロビン方式を使用して順番に試行されます。

connectパラメーターを指定すると、上流サーバーへの接続時間が使用されます。first_byteパラメーターを指定すると、データの最初のバイト受信時間が使用されます。last_byteを指定すると、データの最後のバイト受信時間が使用されます。inflightパラメーターを指定した場合 (1.11.6)、未完了の接続も考慮されます。

バージョン1.11.6より前は、未完了の接続がデフォルトで考慮されていました。

このディレクティブは、当社の商用サブスクリプションの一部として提供されています。

サーバーの重みを考慮して、ランダムに選択されたサーバーに接続が渡されるロードバランシング方式を使用するグループを指定します。

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

least_timeメソッドは、平均時間が最も短く、アクティブな接続数が最も少ないサーバーに接続を渡します。least_time=connectパラメーターを指定すると、上流サーバーへの接続時間が使用されます。least_time=first_byteパラメーターを指定すると、データの最初のバイト受信時間が使用されます。least_time=last_byteを指定すると、データの最後のバイト受信時間が使用されます。

least_timeメソッドは、当社の商用サブスクリプションの一部として提供されています。

アップストリームサーバーのホスト名をアドレスに解決するために使用される名前サーバーを設定します。例：

resolver 127.0.0.1 [::1]:5353;

アドレスは、ドメイン名またはIPアドレスで指定でき、オプションでポートを指定できます。ポートが指定されていない場合は、ポート53が使用されます。名前サーバーはラウンドロビン方式でクエリされます。

デフォルトでは、nginxはIPv4とIPv6の両方のアドレスを解決時に検索します。IPv4またはIPv6アドレスの検索が不要な場合は、ipv4=off (1.23.1)またはipv6=offパラメーターを指定できます。

デフォルトでは、nginxはレスポンスのTTL値を使用して回答をキャッシュします。オプションのvalidパラメーターを使用すると、これを上書きできます。

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

DNSスプーフィングを防ぐために、適切に保護された信頼できるローカルネットワークでDNSサーバーを設定することをお勧めします。

オプションのstatus_zoneパラメーターにより、指定されたzoneに、リクエストとレスポンスのDNSサーバー統計の収集が有効になります。

このディレクティブは、当社の商用サブスクリプションの一部として提供されています。

resolver_timeout 30s;

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

resolver_timeout 5s;

このディレクティブは、当社の商用サブスクリプションの一部として提供されています。

ngx_stream_upstream_moduleモジュールは、次の組み込み変数をサポートしています。

$upstream_addr

アップストリームサーバーのIPアドレスとポート、またはUNIXドメインソケットへのパスを保持します (1.11.4)。プロキシ中に複数のサーバーに接続された場合、それらのアドレスはコンマで区切られます（例：「192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock」）。サーバーを選択できない場合、変数はサーバーグループの名前を保持します。

$upstream_bytes_received

アップストリームサーバーから受信したバイト数 (1.11.4)。複数の接続からの値は、$upstream_addr変数のアドレスのようにコンマで区切られます。

$upstream_bytes_sent

アップストリームサーバーに送信したバイト数 (1.11.4)。複数の接続からの値は、$upstream_addr変数のアドレスのようにコンマで区切られます。

$upstream_connect_time

アップストリームサーバーへの接続時間 (1.11.4)。時間はミリ秒単位の精度で秒単位で保持されます。複数の接続の時間は、$upstream_addr変数のアドレスのようにコンマで区切られます。

$upstream_first_byte_time

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

$upstream_session_time

セッション時間（ミリ秒単位の精度で秒単位）(1.11.4)。複数の接続の時間は、$upstream_addr変数のアドレスのようにコンマで区切られます。