ngx_http_upstream_conf_module モジュール

ngx_http_upstream_conf_module モジュールを使うと、nginx を再起動することなく、シンプルな HTTP インターフェースを介して、オンザフライでアップストリームサーバグループを設定できます。http または stream のサーバグループは、共有メモリに存在する必要があります。

このモジュールは、1.13.10 までは当社の商用サブスクリプションの一部として提供されていました。1.13.3 で ngx_http_api_module モジュールに置き換えられました。

設定例

upstream backend {
    zone upstream_backend 64k;

    ...
}

server {
    location /upstream_conf {
        upstream_conf;
        allow 127.0.0.1;
        deny all;
    }
}

ディレクティブ

構文	`upstream_conf;`
デフォルト	—
コンテキスト	`location`

囲まれた location 内で、アップストリーム設定の HTTP インターフェースを有効にします。この location へのアクセスは、制限する必要があります。

設定コマンドは、次の目的で使用できます

グループ構成の表示。
サーバの表示、変更、または削除。
新しいサーバの追加。

グループ内のアドレスは一意である必要がないため、グループ内の特定のサーバは、ID で参照されます。ID は自動的に割り当てられ、新しいサーバを追加するとき、またはグループ構成を表示するときに表示されます。

設定コマンドは、リクエスト引数として渡されるパラメータで構成されます。例:

http://127.0.0.1/upstream_conf?upstream=backend

以下のパラメータがサポートされています。

stream=: stream アップストリームサーバグループを選択します。このパラメータがない場合は、http アップストリームサーバグループを選択します。
upstream=名前: 操作するグループを選択します。このパラメータは必須です。
id=番号: 表示、変更、または削除するサーバを選択します。
remove=: グループからサーバを削除します。
add=: グループに新しいサーバを追加します。
backup=: バックアップサーバを追加するために必要です。
バージョン 1.7.2 より前は、backup= は既存のバックアップサーバを表示、変更、または削除するためにも必要でした。
server=アドレス: http または stream アップストリームサーバの「address」パラメータと同じです。
サーバを追加するときに、ドメイン名として指定できます。この場合、ドメイン名に対応する IP アドレスの変更が監視され、nginx を再起動することなく、自動的にアップストリーム構成に適用されます (1.7.2)。これには、http または stream ブロックの "resolver" ディレクティブが必要です。 http または stream アップストリームサーバの "resolve" パラメータも参照してください。
service=名前: http または stream アップストリームサーバの「service」パラメータと同じです (1.9.13)。
weight=数値: http または stream アップストリームサーバの「weight」パラメータと同じです。
max_conns=数値: http または stream アップストリームサーバの「max_conns」パラメータと同じです。
max_fails=数値: http または stream アップストリームサーバの「max_fails」パラメータと同じです。
fail_timeout=時間: http または stream アップストリームサーバの「fail_timeout」パラメータと同じです。
slow_start=時間: http または stream アップストリームサーバの「slow_start」パラメータと同じです。
down=: http または stream アップストリームサーバの「down」パラメータと同じです。
drain=: http アップストリームサーバを「ドレイン」モードにします (1.7.5)。このモードでは、サーバにバインドされたリクエストのみがプロキシされます。
up=: http または stream アップストリームサーバの「down」パラメータの反対です。
route=文字列: http アップストリームサーバの「route」パラメータと同じです。

最初の3つのパラメータはオブジェクトを選択します。これは、http または stream のアップストリームサーバグループ全体、または特定のサーバのいずれかです。他のパラメータがない場合、選択したグループまたはサーバの設定が表示されます。

たとえば、グループ全体の構成を表示するには、次を送信します

http://127.0.0.1/upstream_conf?upstream=backend

特定のサーバの構成を表示するには、その ID も指定します

http://127.0.0.1/upstream_conf?upstream=backend&id=42

新しいサーバを追加するには、"server=" パラメータにそのアドレスを指定します。他のパラメータを指定しない場合、サーバは他のパラメータがデフォルト値に設定された状態で追加されます(http または stream の "server" ディレクティブを参照)。

たとえば、新しいプライマリサーバを追加するには、次を送信します

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080

新しいバックアップサーバを追加するには、次を送信します

http://127.0.0.1/upstream_conf?add=&upstream=backend&backup=&server=127.0.0.1:8080

新しいプライマリサーバを追加し、そのパラメータをデフォルト以外の値に設定し、"down" としてマークするには、次を送信します

http://127.0.0.1/upstream_conf?add=&upstream=backend&server=127.0.0.1:8080&weight=2&down=

サーバを削除するには、その ID を指定します

http://127.0.0.1/upstream_conf?remove=&upstream=backend&id=42

既存のサーバを "down" としてマークするには、次を送信します

http://127.0.0.1/upstream_conf?upstream=backend&id=42&down=

既存のサーバのアドレスを変更するには、次を送信します

http://127.0.0.1/upstream_conf?upstream=backend&id=42&server=192.0.2.3:8123

既存のサーバの他のパラメータを変更するには、次を送信します

http://127.0.0.1/upstream_conf?upstream=backend&id=42&max_fails=3&weight=4

上記の例は、http アップストリームサーバグループに関するものです。stream アップストリームサーバグループの同様の例では、"stream=" パラメータが必要です。