Модуль ngx_stream_upstream_module

• Пример конфигурации
• Директивы
• upstream
• server
• зона
• состояние
• 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-домена, могут быть смешаны.

Пример:

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

По умолчанию соединения распределяются между серверами с помощью взвешенного алгоритма балансировки round-robin. В приведенном выше примере каждые 7 подключений будут распределены следующим образом: 5 подключений к backend1.example.com:12345 и по одному подключению к каждому из второго и третьего серверов. Если при общении с сервером возникнет ошибка, подключение будет передано следующему серверу и так далее, пока не будут испробованы все работоспособные серверы. Если общение со всеми серверами завершится неудачно, подключение будет закрыто.

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

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

weight=number

устанавливает вес сервера, по умолчанию 1.

max_conns=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.

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 с высоким приоритетом разрешаются как резервные серверы, остальные записи игнорируются.

slow_start=time

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

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

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

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

Кроме того, в рамках нашей коммерческой подписки такие группы позволяют изменять состав группы или изменять настройки определённого сервера без необходимости перезапуска 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;

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

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

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

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

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

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

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

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

Необязательный параметр two указывает nginx на случайный выбор двух серверов, а затем выбор сервера с использованием указанного 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 позволяет собирать статистику DNS-сервера по запросам и ответам в указанной zone.

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

Устанавливает таймаут для разрешения имён, например:

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.