Модуль http_upstream
#
Предоставляет контекст для описания группы серверов, которые могут использоваться в директивах proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass и grpc_pass.
Пример конфигурации#
upstream backend {
zone backend 1m;
server backend1.example.com weight=5;
server backend2.example.com:8080;
server backend3.example.com service=_example._tcp resolve;
server unix:/tmp/backend3;
server backup1.example.com:8080 backup;
server backup2.example.com:8080 backup;
}
resolver 127.0.0.53 status_zone=resolver;
server {
location / {
proxy_pass http://backend;
}
}
Директивы#
upstream#
- Синтаксис:
upstream
имя { … }- Умолчание:
—
- Контекст:
http
Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.
Пример:
upstream backend {
server backend1.example.com weight=5;
server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
server unix:/tmp/backend3;
server backup1.example.com backup;
}
По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учетом весов серверов. В вышеприведенном примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы.
Если при попытке работы с сервером происходит ошибка, то запрос передается следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращен результат работы с последним сервером.
server#
- Синтаксис:
server
адрес [параметры];- Умолчание:
—
- Контекст:
upstream
Задает адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта, или в виде пути UNIX-сокета, который указывается после префикса unix:
. Если порт не указан, используется порт 80. Доменное имя, которому соответствует несколько IP-адресов, задает сразу несколько серверов.
Могут быть заданы следующие параметры:
|
задает вес сервера |
|
ограничивает максимальное число одновременных активных соединений к проксируемому серверу. |
Примечание
При включенных неактивных постоянных соединениях, нескольких рабочих процессах и зоне разделяемой памяти, суммарное число активных и неактивных соединений с проксируемым сервером может превышать значение max_conns.
max_fails=
число — задает число неудачных попыток связи с сервером,
которые должны произойти в течение заданного fail_timeout
времени для того, чтобы сервер считался недоступным;
после этого он будет повторно проверен через то же самое время.
Что считается неудачной попыткой, определяется директивами proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream, memcached_next_upstream и grpc_next_upstream.
При превышении max_fails
сервер также признается неработающим с точки зрения
upstream_probe; клиентские запросы не будут направляться к нему,
пока проверки не признают его работающим.
Примечание
Если в апстриме задан только один server
,
max_fails
не работает и будет игнорироваться.
|
число попыток по умолчанию |
|
отключает учет попыток |
fail_timeout=
время — задает период времени, в течение которого
должно произойти определенное число неудачных попыток связи с сервером
(max_fails), чтобы сервер считался недоступным.
Затем сервер остается недоступным в течение того же самого времени,
прежде чем будет проверен повторно.
Значение по умолчанию — 10 секунд.
Примечание
Если в апстриме задан только один server
,
fail_timeout
не работает и будет игнорироваться.
|
помечает сервер как запасной. На него будут передаваться запросы в случае, если не работают основные серверы. |
|
помечает сервер как постоянно недоступный. |
|
помечает сервер как разгружаемый (draining); это значит,
что он получает только запросы сессий,
привязанных ранее через sticky.
В остальном поведение такое же, как в режиме |
Осторожно
Параметр backup
нельзя использовать совместно с методами
балансировки нагрузки hash, ip_hash и
random.
Параметры down
и drain
взаимно исключающие.
Добавлено в версии 1.1.0.
|
позволяет отслеживать изменения списка IP-адресов, соответствующего доменному имени, и обновлять его без перезагрузки конфигурации. При этом группа должна находиться в зоне разделяемой памяти; также должен быть определен преобразователь имен в адреса. |
|
включает преобразование SRV-записей DNS и задает имя сервиса. Для работы параметра необходимо задать параметр resolve у сервера, не указывая порт сервера при имени хоста. Если в имени службы нет точек, формируется имя по стандарту RFC:
к имени службы добавляется префикс Angie разрешает SRV-записи, объединяя нормализованное имя службы и имя хоста и получая список серверов для полученной комбинации через DNS, вместе с их приоритетами и весами.
|
В этом примере выполняется поиск записи _http._tcp.backend.example.com
:
server backend.example.com service=http resolve;
Добавлено в версии 1.2.0.
|
задает ID сервера в группе. |
Добавлено в версии 1.4.0.
|
задает время восстановления веса сервера, возвращающегося к работе при балансировке нагрузки методом round-robin или least_conn. Если параметр задан и сервер после сбоя снова считается работающим с точки зрения max_fails и upstream_probe, то такой сервер равномерно набирает указанный для него вес в течение заданного времени. Если параметр не задан, то в аналогичной ситуации сервер сразу начинает работу с указанным для него весом. |
Примечание
Если в апстриме задан только один server
,
slow_start
не работает и будет игнорироваться.
zone#
- Синтаксис:
zone
имя [размер];- Умолчание:
—
- Контекст:
upstream
Задает имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и ее рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.
hash#
- Синтаксис:
hash
ключ [consistent];- Умолчание:
—
- Контекст:
upstream
Задает метод балансировки нагрузки для группы, при котором соответствие клиента серверу определяется при помощи хэшированного значения ключа. В качестве ключа может использоваться текст, переменные и их комбинации. Следует отметить, что любое добавление или удаление серверов в группе может привести к перераспределению большинства ключей на другие серверы. Метод совместим с библиотекой Perl Cache::Memcached.
Если задан параметр consistent
, то вместо вышеописанного метода будет использоваться метод консистентного хэширования ketama. Метод гарантирует, что при добавлении сервера в группу или его удалении на другие серверы будет перераспределено минимальное число ключей. Применение метода для кэширующих серверов обеспечивает больший процент попаданий в кэш. Метод совместим с библиотекой Perl Cache::Memcached::Fast при значении параметра ketama_points равным 160.
ip_hash#
- Синтаксис:
ip_hash
;- Умолчание:
—
- Контекст:
upstream
Задает для группы метод балансировки нагрузки, при котором запросы распределяются по серверам на основе IP-адресов клиентов. В качестве ключа для хэширования используются первые три октета IPv4-адреса клиента или IPv6-адрес клиента целиком. Метод гарантирует, что запросы одного и того же клиента будут всегда передаваться на один и тот же сервер. Если же этот сервер будет считаться недоступным, то запросы этого клиента будут передаваться на другой сервер. С большой долей вероятности это также будет один и тот же сервер.
Если один из серверов нужно убрать на некоторое время, то для сохранения текущего хэширования IP-адресов клиентов этот сервер нужно пометить параметром down
:
upstream backend {
ip_hash;
server backend1.example.com;
server backend2.example.com;
server backend3.example.com down;
server backend4.example.com;
}
keepalive#
- Синтаксис:
keepalive
соединения;- Умолчание:
—
- Контекст:
upstream
Задействует кэш соединений для группы серверов.
Параметр соединения
устанавливает максимальное число неактивных
постоянных соединений с серверами группы, которые будут сохраняться в кэше
каждого рабочего процесса. При превышении этого числа наиболее давно не
используемые соединения закрываются.
Примечание
Следует особо отметить, что директива keepalive не ограничивает общее число соединений с серверами группы, которые рабочие процессы Angie могут открыть. Параметр соединения следует устанавливать достаточно консервативно, чтобы серверы группы по-прежнему могли обрабатывать новые входящие соединения.
Внимание
Директива keepalive
должна использоваться после всех директив, задающих
тот или иной метод балансировки нагрузки, иначе она не будет работать.
Пример конфигурации группы серверов memcached с постоянными соединениями:
upstream memcached_backend {
server 127.0.0.1:11211;
server 10.0.0.2:11211;
keepalive 32;
}
server {
#...
location /memcached/ {
set $memcached_key $uri;
memcached_pass memcached_backend;
}
}
Для HTTP директиву proxy_http_version следует установить в «1.1», а поле заголовка «Connection» — очистить:
upstream http_backend {
server 127.0.0.1:8080;
keepalive 16;
}
server {
#...
location /http/ {
proxy_pass http://http_backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
# ...
}
}
Примечание
Хоть это и не рекомендуется, но также возможно использование постоянных соединений с HTTP/1.0, путем передачи поля заголовка «Connection: Keep-Alive» серверу группы.
Для работы постоянных соединений с FastCGI-серверами потребуется включить директиву fastcgi_keep_conn:
upstream fastcgi_backend {
server 127.0.0.1:9000;
keepalive 8;
}
server {
#...
location /fastcgi/ {
fastcgi_pass fastcgi_backend;
fastcgi_keep_conn on;
# ...
}
}
Примечание
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
keepalive_requests#
- Синтаксис:
keepalive_requests
число;- Умолчание:
keepalive_requests 1000;
- Контекст:
upstream
Задает максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.
Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.
keepalive_time#
- Синтаксис:
keepalive_time
время;- Умолчание:
keepalive_time 1h;
- Контекст:
upstream
Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках постоянного соединения. По достижении заданного времени соединение закрывается после обработки очередного запроса.
keepalive_timeout#
- Синтаксис:
keepalive_timeout
время;- Умолчание:
keepalive_timeout 60s;
- Контекст:
upstream
Задает таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.
bind_conn#
Важно
Директива доступна только в версии PRO.
- Синтаксис:
bind_conn
значение;- Умолчание:
—
- Контекст:
upstream
Позволяет привязать серверное соединение к клиентскому в момент, когда
значение, заданное строкой из переменных, становится отличным от ""
и
"0"
.
Внимание
Директива bind_conn
должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Если она используется наряду с директивой sticky,
то bind_conn
должна стоять после sticky
.
Внимание
При использовании директивы настройки модуля http_proxy должны допускать использование постоянных соединений, например:
proxy_http_version 1.1;
proxy_set_header Connection "";
Типичный пример использования директивы — проксирование соединений с NTLM-аутентификацией, где требуется обеспечить привязку клиента к серверу в начале согласования:
map $http_authorization $ntlm {
~*^N(?:TLM|egotiate) 1;
}
upstream ntlm_backend {
server 127.0.0.1:8080;
bind_conn $ntlm;
}
server {
# ...
location / {
proxy_pass http://ntlm_backend;
proxy_http_version 1.1;
proxy_set_header Connection "";
# ...
}
}
least_conn#
- Синтаксис:
least_conn
;- Умолчание:
—
- Контекст:
upstream
Задает для группы метод балансировки нагрузки, при котором запрос передается серверу с наименьшим числом активных соединений, с учетом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учетом их весов.
random#
- Синтаксис:
random
[two];- Умолчание:
—
- Контекст:
upstream
Задает для группы метод балансировки нагрузки, при котором запрос передается случайно выбранному серверу, с учетом весов серверов.
Если указан необязательный параметр two
, Angie случайным образом выбирает два сервера, из которых выбирает сервер, используя метод least_conn, при котором запрос передается на сервер с наименьшим количеством активных соединений.
sticky#
Добавлено в версии 1.2.0.
- Синтаксис:
sticky
cookie name [attr=значение]…;
sticky
route $variable…;
sticky
learn zone=зона create=$variable1… lookup=$cookie1… [header] [timeout=время];- Умолчание:
—
- Контекст:
upstream
Настраивает привязку клиентских сессий к проксируемым серверам
в режиме, заданном первым параметром;
для разгрузки серверов,
у которых задана директива sticky
,
можно использовать опцию drain
в блоке server.
Внимание
Директива sticky
должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Если она используется наряду с директивой bind_conn,
то bind_conn
должна стоять после sticky
.
В этом режиме запрос от клиента, пока не привязанного к какому-то серверу, отправляется на сервер, выбираемый согласно настроенному методу балансировки. При этом данные о выбранном таким образом сервере сохраняются в cookie, который Angie создает специально для этой цели.
Имя cookie (name
) задается самой директивой sticky
,
а значение (value
) соответствует
параметру sid директивы server
(учтите, что параметр дополнительно хэшируется,
если задана директива sticky_secret).
Последующие запросы от клиента, содержащие соответствующий cookie, передаются на сервер, соответствующий значению cookie, то есть имеющий заданный в нем sid. Если выбрать сервер не удается или выбранный таким образом сервер не может обработать запрос, то будет выбран другой сервер согласно настроенному методу балансировки.
Директива позволяет назначать атрибуты такого cookie;
единственный атрибут, устанавливаемый по умолчанию, — path=/
.
Значения атрибутов задаются строками с переменными.
Чтобы удалить атрибут, задайте для него пустое значение: attr=
.
Так, sticky cookie path=
задает cookie без атрибута path
.
Здесь
Angie создает cookie srv_id
со сроком действия в 1 час
и доменом, заданным переменной:
upstream backend {
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky cookie srv_id domain=$my_domain max-age=3600;
}
В этом режиме проксируемый сервер при получении запроса может назначить клиенту маршрут каким-либо способом, понятным клиенту и серверу. В качестве идентификатора маршрута должно использоваться значение параметра sid директивы server (учтите, что параметр дополнительно хэшируется, если задана директива sticky_secret).
Последующие запросы от клиента, желающего использовать такой маршрут, должны содержать выданный сервером идентификатор, причем так, чтобы он попал в переменные Angie, например в cookie или аргументы запроса.
В параметрах директивы указываются конкретные переменные, используемые для маршрутизации. Чтобы выбрать сервер, куда передается поступивший запрос, используется первая непустая переменная; она и сравнивается с параметром sid директивы server. Если выбрать сервер не удается или выбранный таким образом сервер не может обработать запрос, то будет выбран другой сервер согласно настроенному методу балансировки.
Здесь
Angie ищет идентификатор маршрута в cookie route
,
затем в аргументе запроса route
:
upstream backend {
server backend1.example.com:8080 sid="server1";
server backend2.example.com:8080 sid="server2";
sticky route $cookie_route $arg_route;
}
В этом режиме сессия создается на основе ответа проксируемого сервера.
Параметры create
и lookup
перечисляют переменные,
указывающие, как создаются новые и ищутся существующие сессии.
Оба параметра можно использовать по нескольку раз.
Идентификатором сессии служит значение первой непустой переменной,
указанная в create
;
например, это может быть
cookie с проксируемого сервера.
Последующие запросы от клиента, желающего использовать сессию,
должны содержать ее идентификатор,
причем так, чтобы он попал
в первую непустую переменную Angie, указанную в lookup
.
Если выбрать сервер не удается
или выбранный таким образом сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.
Сессии хранятся в зоне общей памяти;
ее имя и размер задаются параметром zone
.
Если к сессии не было обращений в течение времени
timeout
, она удаляется.
Значение по умолчанию — 10 минут.
Параметр header
позволяет создать сессию
сразу после получения заголовков ответа от проксируемого сервера.
Без него сессия создается только после завершения обработки запроса.
В примере Angie создает сессию,
устанавливая в ответе cookie с именем examplecookie
:
upstream backend {
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky learn
create=$upstream_cookie_examplecookie
lookup=$cookie_examplecookie
zone=client_sessions:1m;
}
sticky_strict#
Добавлено в версии 1.2.0.
- Синтаксис:
sticky_strict
on | off;- Умолчание:
sticky_strict off;
- Контекст:
upstream
Позволяет возвращать ошибку 502 в случаях, когда назначенный клиенту сервер в апстриме недоступен.
По умолчанию из группы серверов выбирается другой доступный сервер.
sticky_secret#
Добавлено в версии 1.2.0.
- Синтаксис:
sticky_secret
строка;- Умолчание:
—
- Контекст:
upstream
Добавляет строку как соль в функцию MD5-хэширования
для директивы sticky в режимах cookie
и route
.
Строка может содержать переменные, например $remote_addr:
upstream backend {
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky cookie cookie_name;
sticky_secret my_secret.$remote_addr;
}
Соль добавляется после хэшируемого значения; чтобы независимо проверить механизм хэширования:
$ echo -n "<VALUE><SALT>" | md5sum
Встроенные переменные#
Модуль http_upstream
поддерживает следующие встроенные переменные:
$upstream_addr
#
хранит IP-адрес и порт или путь к UNIX-сокету сервера группы. Если при обработке запроса были сделаны обращения к нескольким серверам, то их адреса разделяются запятой, например:
192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock
Если произошло внутреннее перенаправление от одной группы серверов на другую с помощью «X-Accel-Redirect» или error_page, то адреса, соответствующие разным группам серверов, разделяются двоеточием, например:
192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80
Если сервер не может быть выбран, то переменная хранит имя группы серверов.
$upstream_bytes_received
#
число байт, полученных от сервера группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_bytes_sent
#
число байт, переданных на сервер группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_cache_status
#
хранит статус доступа к кэшу ответов. Статус может быть одним из MISS
,
BYPASS
, EXPIRED
, STALE
, UPDATING
,
REVALIDATED
или HIT
:
MISS
: Ответ не найден в кэше, и запрос передан на сервер.BYPASS
: Кэш обойден, и запрос напрямую передан на сервер.EXPIRED
: Ответ в кэше устарел, и на сервер передан новый запрос для обновления контента.STALE
: Ответ в кэше устарел, но по-прежнему передается клиентам, пока через какое-то время не произойдет обновление контента c сервера.UPDATING
: Ответ в кэше устарел, но по-прежнему передается клиентам, пока уже идущее обновление контента c сервера не завершится.REVALIDATED
: Ответ в кэше устарел, но был успешно перепроверен и не нуждается в обновлении с сервера.HIT
: Ответ был взят из кэша.
Если запрос пошел в обход кэша без обращения к нему, переменная не устанавливается.
$upstream_connect_time
#
хранит время, затраченное на установление соединения с сервером группы; время хранится в секундах с точностью до миллисекунд. В случае SSL включает в себя время, потраченное на рукопожатие. Времена нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_header_time
#
хранит время, затраченное на получение заголовка ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_http_
имя#
хранят поля заголовка ответа сервера. Например, поле заголовка ответа «Server» доступно в переменной $upstream_http_server. Правила преобразования имен полей заголовка ответа в имена переменных такие же, как для переменных с префиксом «$http_». Необходимо иметь в виду, что поля заголовка запоминаются только из ответа последнего сервера.
$upstream_probe_body
(PRO)#
Тело ответа от сервера, полученного при проверке
upstream_probe.
Его размер ограничен параметром max_body
.
$upstream_queue_time
#
хранит время, проведенное запросом в очереди до очередного выбора сервера и выраженное в секундах с точностью до миллисекунд. Времена нескольких попыток разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_response_length
#
хранит длину ответа, полученного от сервера группы; длина хранится в байтах. Длины нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_response_time
#
хранит время, затраченное на получение ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_status
#
хранит статус ответа, полученного от сервера группы. Статусы нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr. Если сервер не может быть выбран, то переменная хранит статус 502 (Bad Gateway).
$upstream_sticky_status
#
Статус привязанного запроса.
|
запрос к upstream не обрабатывался модулем http_upstream_sticky |
|
запрос не содержит информации о привязке к серверу |
|
запрос с привязкой отправлен на соответствующий сервер |
|
запрос с привязкой отправлен на сервер, выбранный по алгоритму балансировки |
Статусы нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной $upstream_addr.
$upstream_trailer_
имя#
хранит поля из конца ответа, полученного от сервера группы.