Модуль `stream_upstream`#

Предоставляет контекст для описания группы серверов, которые могут использоваться в директиве proxy_pass.

Пример конфигурации#

upstream backend {
    hash $remote_addr consistent;
    zone backend 1m;

    server backend1.example.com:1935  weight=5;
    server unix:/tmp/backend3;
    server backend3.example.com       service=_example._tcp resolve;

    server backup1.example.com:1935   backup;
    server backup2.example.com:1935   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    listen 1936;
    proxy_pass backend;
}

Директивы#

upstream#

Синтаксис:: upstream имя { … }
Умолчание:: —
Контекст:: stream

Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.

Пример:

upstream backend {
    server backend1.example.com:1935 weight=5;
    server 127.0.0.1:1935            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:1935 resolve;

    server backup1.example.com:1935  backup;
}

По умолчанию соединения распределяются по серверам циклически (в режиме round-robin) с учетом весов серверов. В вышеприведенном примере каждые 7 соединений будут распределены так: 5 соединений на backend1.example.com:1935 и по одному соединению на второй и третий серверы.

Если при попытке работы с сервером происходит ошибка, то соединение передается следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если связь с серверами не удалась, соединение будет закрыто.

server#

Синтаксис:: server адрес [параметры];
Умолчание:: —
Контекст:: upstream

Задает адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и обязательного порта, или в виде пути UNIX-сокета, который указывается после префикса unix:. Доменное имя, которому соответствует несколько IP-адресов, задает сразу несколько серверов.

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

weight=число

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

max_conns=число

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

max_fails=число — задает число неудачных попыток связи с сервером, которые должны произойти в течение заданного fail_timeout времени для того, чтобы сервер считался недоступным; после этого он будет повторно проверен через то же самое время.

В данном случае неудачной попыткой считается ошибка или таймаут при установке соединения с сервером.

Примечание

Если в апстриме задан только один server, max_fails не работает и будет игнорироваться.

`max_fails=1`	число попыток по умолчанию
`max_fails=0`	отключает учет попыток

fail_timeout=время — задает:

fail_timeout=время — задает период времени, в течение которого должно произойти определенное число неудачных попыток связи с сервером (max_fails), чтобы сервер считался недоступным. Затем сервер остается недоступным в течение того же самого времени, прежде чем будет проверен повторно.

Значение по умолчанию — 10 секунд.

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

Осторожно

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

Added in version 1.3.0.

resolve

Позволяет отслеживать изменения списка IP-адресов, соответствующего доменному имени, и обновлять его без перезагрузки конфигурации. При этом группа должна находиться в зоне разделяемой памяти; также должен быть определен преобразователь имен в адреса.

service=имя

Включает преобразование SRV-записей DNS и задает имя сервиса. При указании этого параметра необходимо также задать параметр resolve, не указывая порт сервера при имени хоста.

Если в имени службы нет точек, формируется имя по стандарту RFC: к имени службы добавляется префикс _, затем через точку добавляется _tcp. Так, имя службы http даст в результате _http._tcp.

Angie PRO разрешает SRV-записи, объединяя нормализованное имя службы и имя хоста и получая список серверов для полученной комбинации через DNS, вместе с их приоритетами и весами.

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

В этом примере выполняется поиск записи _http._tcp.backend.example.com:

server backend.example.com service=http resolve;

Added in version 1.4.0.

slow_start=время

задает время восстановления веса сервера, возвращающегося к работе при балансировке нагрузки методом round-robin или least_conn.

Если параметр задан и сервер после сбоя снова считается работающим с точки зрения max_fails и upstream_probe (PRO), то такой сервер равномерно набирает указанный для него вес в течение заданного времени.

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

Примечание

Если в апстриме задан только один server, slow_start не работает и будет игнорироваться.

state (PRO)#

Added in version 1.4.0: PRO

Синтаксис:: state файл;
Умолчание:: —
Контекст:: upstream

Указывает файл, где постоянно хранится список серверов апстрима. При установке из наших пакетов для хранения таких файлов специально создается каталог /var/lib/angie/state/ (/var/db/angie/state/ во FreeBSD) с соответствующими правами доступа, и в конфигурации остается добавить лишь имя файла:

upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<ИМЯ ФАЙЛА>;
}

Список серверов здесь имеет формат, аналогичный s_server. Содержимое файла изменяется при любом изменении серверов в разделе /config/stream/upstreams/ через API конфигурации. Файл считывается при запуске Angie PRO или перезагрузке конфигурации.

Осторожно

Чтобы использовать директиву state в блоке upstream, в нем не должно быть директив server, но нужна зона разделяемой памяти (zone).

zone#

Синтаксис:: zone имя [размер];
Умолчание:: —
Контекст:: upstream

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

hash#

Синтаксис:: hash ключ [consistent];
Умолчание:: —
Контекст:: upstream

Задает метод балансировки нагрузки для группы, при котором соответствие клиента серверу определяется при помощи хэшированного значения ключа. В качестве ключа может использоваться текст, переменные и их комбинации. Пример использования:

hash $remote_addr;

Метод совместим с библиотекой Perl Cache::Memcached.

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

least_conn#

Синтаксис:: least_conn;
Умолчание:: —
Контекст:: upstream

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

least_time (PRO)#

Синтаксис:: least_time connect | first_byte | last_byte;
Умолчание:: —
Контекст:: upstream

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

В режиме connect учитывается среднее время установки соединения; в режиме first_byte — среднее время получения первого байта ответа; в режиме last_byte — среднее время получения полного ответа.

Подсчет средних значений управляется директивой response_time_factor (PRO). Текущие значения представлены как connect_time, first_byte_time и last_byte_time в объекте health сервера среди метрик апстрима в API.

random#

Синтаксис:: random [two];
Умолчание:: —
Контекст:: upstream

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

Если указан необязательный параметр two, Angie PRO случайным образом выбирает два сервера, из которых выбирает сервер, используя указанный метод. Методом по умолчанию является least_conn, при котором соединение передается на сервер с наименьшим количеством активных соединений.

response_time_factor (PRO)#

Синтаксис:: response_time_factor число;
Умолчание:: response_time_factor 90;
Контекст:: upstream

Задает для метода балансировки нагрузки least_time (PRO) коэффициент сглаживания предыдущего значения при вычислении среднего времени ответа по формуле экспоненциально взвешенного скользящего среднего.

Чем больше указанное число, тем меньше новые значения влияют на среднее; если указать 90, то будет взято 90 % от предыдущего значения и лишь 10 % от нового. Допустимые значения — от 0 до 99 включительно.

Текущие результаты вычислений представлены как connect_time (время установления соединения), first_byte_time (время получения первого байта ответа) и last_byte_time (время получения ответа целиком) в объекте health сервера среди метрик апстрима в API.

Примечание

При подсчете учитываются только успешные ответы; что считать неуспешным ответом, определяют директивы proxy_next_upstream.

sticky#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Синтаксис:: sticky route $variable…;
sticky learn zone=zone create=$create_var1… lookup=$lookup_var1… [connect] [timeout=time];
Умолчание:: —
Контекст:: upstream

Настраивает привязку клиентских сессий к проксируемым серверам в режиме, заданном первым параметром.

Внимание

Директива sticky должна использоваться после всех директив, задающих тот или иной метод балансировки нагрузки, иначе она не будет работать.

Этот режим использует предопределенные идентификаторы маршрутов, которые могут быть встроены в свойства соединения, доступные Angie PRO. Он менее гибок, так как зависит от предопределенных значений, но лучше подходит, если такие идентификаторы уже используются.

Здесь при установлении соединения проксируемый сервер может назначить клиенту маршрут и вернуть его идентификатор способом, известным им обоим. В качестве идентификатора маршрута должно использоваться значение параметра sid директивы server. Учтите, что параметр дополнительно хэшируется, если задана директива sticky_secret.

Последующие соединения от клиентов, желающих использовать этот маршрут, должны содержать выданный сервером идентификатор, причем так, чтобы он попал в переменные Angie PRO.

В параметрах директивы указываются переменные для маршрутизации. Чтобы выбрать сервер, куда направляется входящее соединение, используется первая непустая переменная; она затем сравнивается с параметром sid директивы server. Если выбрать сервер не удается или выбранный сервер не может принять соединение, то будет выбран другой сервер согласно настроенному методу балансировки.

Здесь Angie PRO ищет идентификатор маршрута в переменной $route, получающей значение на основе $ssl_preread_server_name (обратите внимание, что нужно включить ssl_preread):

stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}

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

Здесь сессия создается на основе свойств соединения, идущих от проксируемого сервера. С параметрами create и lookup перечисляются переменные, указывающие, как создаются новые и ищутся существующие сессии. Оба параметра можно использовать по нескольку раз.

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

Сессии хранятся в зоне общей памяти; ее имя и размер задаются параметром zone. Если к сессии не было обращений в течение времени timeout, она удаляется. Значение по умолчанию — 1 час.

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

Параметр connect позволяет создать сессию сразу после получения заголовков ответа от проксируемого сервера. Без него сессия создается только после завершения обработки со.

В примере Angie PRO создает и ищет сессии, используя переменную $rdp_cookie:

stream {

    upstream backend {

        server 127.0.0.1:3390 sid=a;
        server 127.0.0.1:3391 sid=b;

        sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
    }

    server {

        listen 127.0.0.1:3389;

        ssl_preread on;

        proxy_pass backend;
    }
}

sticky_strict#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Синтаксис:: sticky_strict on | off;
Умолчание:: sticky_strict off;
Контекст:: upstream

При включении Angie PRO будет возвращать клиенту ошибку соединения, если желаемый сервер недоступен, вместо использования любого другого доступного сервера, как это происходит, когда в группе нет доступных серверов.

sticky_secret#

Added in version 1.6.0: Angie

Added in version 1.6.0: Angie PRO

Синтаксис:: sticky_secret строка;
Умолчание:: —
Контекст:: upstream

Добавляет строку как соль в функцию MD5-хэширования для директивы sticky в режиме route. Строка может содержать переменные, например $remote_addr:

upstream backend {
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}

Соль добавляется после хэшируемого значения; чтобы независимо проверить механизм хэширования:

$ echo -n "<VALUE><SALT>" | md5sum

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

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

`$upstream_addr`#

хранит IP-адрес и порт или путь к UNIX-сокету сервера группы. Если при проксировании были сделаны обращения к нескольким серверам, то их адреса разделяются запятой, например:

192.168.1.1:1935, 192.168.1.2:1935, unix:/tmp/sock»

Если сервер не может быть выбран, то переменная хранит имя группы серверов.

`$upstream_bytes_received`#

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

`$upstream_bytes_sent`#

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

`$upstream_connect_time`#

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

`$upstream_first_byte_time`#

время получения первого байта данных; время хранится в секундах с точностью до миллисекунд. Времена нескольких соединений разделяются запятыми подобно адресам в переменной $upstream_addr.

`$upstream_session_time`#

длительность сессии в секундах с точностью до миллисекунд. Времена нескольких соединений разделяются запятыми подобно адресам в переменной $upstream_addr.

`$upstream_sticky_status`#

Статус соединений с привязкой.

`""`	Соединение направлено в группу серверов, где привязка не используется.
`NEW`	Соединение не содержит информации о привязке к серверу.
`HIT`	Соединение с привязкой направлено на желаемый сервер.
`MISS`	Соединение с привязкой направлено на сервер, выбранный по алгоритму балансировки.

Статусы из нескольких соединений разделяются запятыми и двоеточиями аналогично адресам в переменной $upstream_addr.

Модуль stream_upstream

Содержание

Модуль `stream_upstream`#

Пример конфигурации#

Директивы#

upstream#

server#

state (PRO)#

zone#

hash#

least_conn#

least_time (PRO)#

random#

response_time_factor (PRO)#

sticky#

sticky_strict#

sticky_secret#

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

`$upstream_addr`#

`$upstream_bytes_received`#

`$upstream_bytes_sent`#

`$upstream_connect_time`#

`$upstream_first_byte_time`#

`$upstream_session_time`#

`$upstream_sticky_status`#

Модуль stream_upstream

Содержание

Модуль stream_upstream#

Пример конфигурации#

Директивы#

upstream#

server#

state (PRO)#

zone#

hash#

least_conn#

least_time (PRO)#

random#

response_time_factor (PRO)#

sticky#

sticky_strict#

sticky_secret#

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

$upstream_addr#

$upstream_bytes_received#

$upstream_bytes_sent#

$upstream_connect_time#

$upstream_first_byte_time#

$upstream_session_time#

$upstream_sticky_status#

Модуль `stream_upstream`#

`$upstream_addr`#

`$upstream_bytes_received`#

`$upstream_bytes_sent`#

`$upstream_connect_time`#

`$upstream_first_byte_time`#

`$upstream_session_time`#

`$upstream_sticky_status`#