Модуль ngx_stream_upstream_module

• Пример конфигурации
• Директивы
• upstream
• server
• zone
• state
• hash
• least_conn
• least_time
• random
• resolver
• resolver_timeout
• Встроенные переменные

Модуль 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-domain-сокеты.

Пример:

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, а по одному соединению — на второй и третий серверы. Если при обмене данными с сервером возникает ошибка, соединение передаётся следующему серверу и так далее, пока не будут проверены все работающие серверы. Если обмен данными со всеми серверами завершается неудачей, соединение закрывается.

Определяет address и другие parameters сервера. Адрес можно указать в виде доменного имени или IP-адреса с обязательным номером порта либо в виде пути к UNIX-domain-сокету, указанного после префикса «unix:». Доменное имя, разрешающееся в несколько IP-адресов, сразу определяет несколько серверов.

Можно задать следующие параметры:

weight=number

задаёт вес сервера; по умолчанию равен 1.

max_conns=number

ограничивает максимальное number одновременных соединений с проксируемым сервером (1.11.5). Значение по умолчанию — ноль, то есть ограничение отсутствует. Если группа серверов не находится в разделяемой памяти, ограничение действует отдельно для каждого рабочего процесса.

До версии 1.11.5 этот параметр был доступен в рамках нашей коммерческой подписки.

max_fails=number

задаёт количество неудачных попыток обмена данными с сервером, которые должны произойти за период, заданный параметром fail_timeout, чтобы сервер считался недоступным в течение периода, также заданного параметром fail_timeout. По умолчанию количество неудачных попыток равно 1. Нулевое значение отключает учёт попыток. Неудачной попыткой считается ошибка или тайм-аут при установлении соединения с сервером.

fail_timeout=time

задаёт

• период, в течение которого должно произойти указанное количество неудачных попыток обмена данными с сервером, чтобы сервер считался недоступным;
• а также период, в течение которого сервер будет считаться недоступным.

По умолчанию параметр установлен в 10 секунд.

backup

помечает сервер как резервный. Соединения будут передаваться резервному серверу, когда основные серверы недоступны.

Параметр нельзя использовать вместе с методами балансировки нагрузки hash и random.

down

помечает сервер как постоянно недоступный.

resolve

отслеживает изменения IP-адресов, соответствующих доменному имени сервера, и автоматически изменяет конфигурацию upstream без необходимости перезапуска nginx. Группа серверов должна находиться в разделяемой памяти.

Чтобы этот параметр работал, директива resolver должна быть указана в блоке stream или в соответствующем блоке upstream.

До версии 1.27.3 этот параметр был доступен только в рамках нашей коммерческой подписки.

service=name

включает разрешение DNS-записей SRV и задаёт имя службы name (1.9.13). Чтобы этот параметр работал, необходимо задать для сервера параметр resolve и указать имя хоста без номера порта.

Если имя службы не содержит точку («.»), формируется соответствующее стандарту RFC имя, а к префиксу службы добавляется протокол TCP. Например, чтобы выполнить поиск записи SRV _http._tcp.backend.example.com, необходимо указать директиву:

server backend.example.com service=http resolve;

Если имя службы содержит одну или несколько точек, имя формируется путём объединения префикса службы и имени сервера. Например, чтобы выполнить поиск записей SRV _http._tcp.backend.example.com и server1.backend.example.com, необходимо указать директивы:

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

Записи SRV с наивысшим приоритетом (записи с одинаковым наименьшим значением приоритета) разрешаются как основные серверы, остальные записи SRV — как резервные серверы. Если для сервера указан параметр backup, записи SRV с высоким приоритетом разрешаются как резервные серверы, а остальные записи SRV игнорируются.

До версии 1.27.3 этот параметр был доступен только в рамках нашей коммерческой подписки.

Кроме того, в рамках нашей коммерческой подписки доступны следующие параметры:

slow_start=time

задаёт time, в течение которого вес сервера будет постепенно увеличиваться от нуля до номинального значения, если нездоровый сервер становится работоспособным или сервер становится доступным после периода, когда он считался недоступным. Значение по умолчанию — ноль, то есть медленный старт отключён.

Параметр нельзя использовать вместе с методами балансировки нагрузки hash и random.

Если в группе только один сервер, параметры max_fails, fail_timeout и slow_start игнорируются, и такой сервер никогда не будет считаться недоступным.

Определяет name и size зоны разделяемой памяти, в которой хранится конфигурация группы и её состояние во время выполнения, совместно используемые рабочими процессами. Несколько групп могут использовать одну и ту же зону. В этом случае достаточно указать size только один раз.

Кроме того, в рамках нашей коммерческой подписки такие группы позволяют изменять состав группы или настройки отдельного сервера без необходимости перезапуска nginx. Конфигурация доступна через модуль API (1.13.3).

До версии 1.13.3 конфигурация была доступна только через специальный location, обрабатываемый директивой 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;

Обратите внимание, что добавление или удаление сервера из группы может привести к переназначению большинства ключей другим серверам. Метод совместим с библиотекой Perl Cache::Memcached.

Если указан параметр consistent, вместо него будет использоваться метод согласованного хеширования ketama. Этот метод гарантирует, что при добавлении сервера в группу или его удалении лишь небольшое количество ключей будет переназначено другим серверам. Это позволяет добиться более высокого коэффициента попаданий в кэш на серверах кэширования. Метод совместим с библиотекой Perl Cache::Memcached::Fast, если для параметра ketama_points задано значение 160.

Указывает, что для группы следует использовать метод балансировки нагрузки, при котором соединение передаётся серверу с наименьшим количеством активных соединений с учётом весов серверов. Если таких серверов несколько, они перебираются по очереди методом взвешенного циклического перебора.

Указывает, что для группы следует использовать метод балансировки нагрузки, при котором соединение передаётся серверу с наименьшим средним временем и наименьшим количеством активных соединений с учётом весов серверов. Если таких серверов несколько, они перебираются по очереди методом взвешенного циклического перебора.

Если указан параметр connect, используется время подключения к upstream-серверу. Если указан параметр first_byte, используется время получения первого байта данных. Если указан параметр last_byte, используется время получения последнего байта данных. Если указан параметр inflight (1.11.6), также учитываются незавершённые соединения.

До версии 1.11.6 незавершённые соединения учитывались по умолчанию.

До версии 1.31.0 эта директива была доступна только в рамках нашей коммерческой подписки.

Указывает, что для группы следует использовать метод балансировки нагрузки, при котором соединение передаётся случайно выбранному серверу с учётом весов серверов.

Необязательный параметр two указывает nginx случайным образом выбрать два сервера, а затем выбрать один из них с помощью указанного method. По умолчанию используется метод least_conn, при котором соединение передаётся серверу с наименьшим количеством активных соединений.

Метод least_time передаёт соединение серверу с наименьшим средним временем и наименьшим количеством активных соединений. Если указан параметр least_time=connect, используется время подключения к upstream-серверу. Если указан параметр least_time=first_byte, используется время получения первого байта данных. Если указан параметр least_time=last_byte, используется время получения последнего байта данных.

Метод least_time доступен в рамках нашей коммерческой подписки.

Настраивает серверы имён, используемые для преобразования имён upstream-серверов в адреса, например:

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 (1.17.5) включает сбор статистики запросов и ответов DNS-сервера в указанной zone. Параметр доступен в рамках нашей коммерческой подписки.

Начиная с версии 1.17.5 и до версии 1.27.3 эта директива была доступна только в рамках нашей коммерческой подписки.

Задаёт тайм-аут разрешения имён, например:

resolver_timeout 5s;

Начиная с версии 1.17.5 и до версии 1.27.3 эта директива была доступна только в рамках нашей коммерческой подписки.

Встроенные переменные

Модуль ngx_stream_upstream_module поддерживает следующие встроенные переменные:

$upstream_addr

содержит IP-адрес и порт либо путь к UNIX-domain-сокету upstream-сервера (1.11.4). Если при проксировании было установлено соединение с несколькими серверами, их адреса разделяются запятыми, например: «192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock». Если сервер не удаётся выбрать, переменная содержит имя группы серверов.

$upstream_bytes_received

количество байтов, полученных от upstream-сервера (1.11.4). Значения для нескольких соединений разделяются запятыми, как адреса в переменной $upstream_addr.

$upstream_bytes_sent

количество байтов, отправленных 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_last_addr

содержит IP-адрес или путь к UNIX-domain-сокету последнего выбранного upstream-сервера (1.29.3).

Эта переменная доступна в рамках нашей коммерческой подписки.

$upstream_session_time

длительность сеанса в секундах с точностью до миллисекунд (1.11.4). Значения для нескольких соединений разделяются запятыми, как адреса в переменной $upstream_addr.