Upstream nginx что это
Модуль ngx_stream_upstream_module
Модуль ngx_stream_upstream_module (1.9.0) позволяет описывать группы серверов, которые могут использоваться в директиве proxy_pass.
Пример конфигурации
Динамически настраиваемая группа с периодическими проверками работоспособности доступна как часть коммерческой подписки:
Директивы
Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.
По умолчанию соединения распределяются по серверам циклически (в режиме round-robin) с учётом весов серверов. В вышеприведённом примере каждые 7 соединений будут распределены так: 5 соединений на backend1.example.com:12345 и по одному соединению на второй и третий серверы. Если при попытке работы с сервером происходит ошибка, то соединение передаётся следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если связь с серверами не удалась, соединение будет закрыто.
| Синтаксис: | server адрес [ параметры ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Задаёт адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и обязательного порта, или в виде пути UNIX-сокета, который указывается после префикса “ unix: ”. Доменное имя, которому соответствует несколько IP-адресов, задаёт сразу несколько серверов.
Могут быть заданы следующие параметры:
weight = число задаёт вес сервера, по умолчанию 1. max_conns = число ограничивает максимальное число одновременных соединений к проксируемому серверу (1.11.5). Значение по умолчанию равно 0 и означает, что ограничения нет. Если группа не находится в зоне разделяемой памяти, то ограничение работает отдельно для каждого рабочего процесса.
До версии 1.11.5 этот параметр был доступен как часть коммерческой подписки.
Параметр нельзя использовать совместно с методами балансировки нагрузки hash и random.
Кроме того, следующие параметры доступны как часть коммерческой подписки:
resolve отслеживает изменения IP-адресов, соответствующих доменному имени сервера, и автоматически изменяет конфигурацию группы без необходимости перезапуска nginx. Группа должна находиться в зоне разделяемой памяти.
Для работы этого параметра директива resolver должна быть задана в блоке stream или в соответствующем блоке upstream.
service = имя включает преобразование SRV-записей DNS и задаёт имя сервиса (1.9.13). Для работы параметра необходимо указать параметр resolve для сервера и не указывать порт сервера.
Если имя сервиса содержит одну и более точек, то имя составляется при помощи соединения префикса службы и имени сервера. Например, для получения SRV-записей _http._tcp.backend.example.com и server1.backend.example.com необходимо указать директивы:
SRV-записи с наивысшим приоритетом (записи с одинаковым наименьшим значением приоритета) преобразуются в основные серверы, остальные SRV-записи преобразуются в запасные серверы. Если в конфигурации сервера указан параметр backup, высокоприоритетные SRV-записи преобразуются в запасные серверы, остальные SRV-записи игнорируются.
Параметр нельзя использовать совместно с методами балансировки нагрузки hash и random.
| Синтаксис: | zone имя [ размер ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Задаёт имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и её рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.
Дополнительно, как часть коммерческой подписки, в таких группах для изменения состава группы или настроек отдельных серверов нет необходимости перезапускать nginx. Конфигурация доступна через модуль API (1.13.3).
До версии 1.13.3 конфигурация была доступна только через специальный location, в котором указана директива upstream_conf.
| Синтаксис: | state файл ; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.9.7.
В данный момент состояние ограничено списком серверов с их параметрами. Файл читается при парсинге конфигурации и обновляется каждый раз при изменении конфигурации группы. Изменение содержимого файла напрямую не рекомендуется. Директиву нельзя использовать совместно с директивой server.
| Синтаксис: | hash ключ [ consistent ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Следует отметить, что любое добавление или удаление серверов в группе может привести к перераспределению большинства ключей на другие серверы. Метод совместим с библиотекой Perl Cache::Memcached.
| Синтаксис: | least_conn; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Задаёт для группы метод балансировки нагрузки, при котором соединение передаётся серверу с наименьшим числом активных соединений, с учётом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учётом их весов.
| Синтаксис: | least_time connect | first_byte | last_byte [ inflight ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Задаёт для группы метод балансировки нагрузки, при котором соединение передаётся серверу с наименьшими средним временем ответа и числом активных соединений с учётом весов серверов. Если подходит сразу несколько серверов, то они выбираются циклически (в режиме round-robin) с учётом их весов.
До версии 1.11.6 незавершённые соединения учитывались по умолчанию.
| Синтаксис: | random [ two [ метод ]]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.15.1.
Задаёт для группы метод балансировки нагрузки, при котором соединение передаётся случайно выбранному серверу, с учётом весов серверов.
Эта директива появилась в версии 1.17.5.
Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов в адреса, например:
Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта. Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.
По умолчанию nginx кэширует ответы, используя значение TTL из ответа. Необязательный параметр valid позволяет это переопределить:
Для предотвращения DNS-спуфинга рекомендуется использовать DNS-серверы в защищённой доверенной локальной сети.
| Синтаксис: | resolver_timeout время ; |
|---|---|
| Умолчание: | |
| Контекст: | upstream |
Эта директива появилась в версии 1.17.5.
Задаёт таймаут для преобразования имени в адрес, например:
Встроенные переменные
Модуль ngx_stream_upstream_module поддерживает следующие встроенные переменные:
Модуль ngx_http_upstream_module
Модуль ngx_http_upstream_module позволяет описывать группы серверов, которые могут использоваться в директивах proxy_pass, fastcgi_pass, uwsgi_pass, scgi_pass, memcached_pass и grpc_pass.
Пример конфигурации
Динамически настраиваемая группа с периодическими проверками работоспособности доступна как часть коммерческой подписки:
Директивы
Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.
По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учётом весов серверов. В вышеприведённом примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы. Если при попытке работы с сервером происходит ошибка, то запрос передаётся следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращён результат работы с последним сервером.
| Синтаксис: | server адрес [ параметры ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Задаёт адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта, или в виде пути UNIX-сокета, который указывается после префикса “ unix: ”. Если порт не указан, используется порт 80. Доменное имя, которому соответствует несколько IP-адресов, задаёт сразу несколько серверов.
Могут быть заданы следующие параметры:
weight = число задаёт вес сервера, по умолчанию 1. max_conns = число ограничивает максимальное число одновременных активных соединений к проксируемому серверу (1.11.5). Значение по умолчанию равно 0 и означает, что ограничения нет. Если группа не находится в зоне разделяемой памяти, то ограничение работает отдельно для каждого рабочего процесса.
Начиная с версии 1.5.9 и до версии 1.11.5 этот параметр был доступен как часть коммерческой подписки.
Параметр нельзя использовать совместно с методами балансировки нагрузки hash, ip_hash и random.
Кроме того, следующие параметры доступны как часть коммерческой подписки:
resolve отслеживает изменения IP-адресов, соответствующих доменному имени сервера, и автоматически изменяет конфигурацию группы без необходимости перезапуска nginx (1.5.12). Группа должна находиться в зоне разделяемой памяти.
Для работы этого параметра директива resolver должна быть задана в блоке http или в соответствующем блоке upstream.
route = строка задаёт имя маршрута к серверу. service = имя включает преобразование SRV-записей DNS и задаёт имя сервиса (1.9.13). Для работы параметра необходимо указать параметр resolve для сервера и не указывать порт сервера.
Если имя сервиса содержит одну и более точек, то имя составляется при помощи соединения префикса службы и имени сервера. Например, для получения SRV-записей _http._tcp.backend.example.com и server1.backend.example.com необходимо указать директивы:
SRV-записи с наивысшим приоритетом (записи с одинаковым наименьшим значением приоритета) преобразуются в основные серверы, остальные SRV-записи преобразуются в запасные серверы. Если в конфигурации сервера указан параметр backup, высокоприоритетные SRV-записи преобразуются в запасные серверы, остальные SRV-записи игнорируются.
Параметр нельзя использовать совместно с методами балансировки нагрузки hash, ip_hash и random.
До версии 1.13.6 параметр мог быть изменён только при помощи модуля API.
| Синтаксис: | zone имя [ размер ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.9.0.
Задаёт имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и её рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.
Дополнительно, как часть коммерческой подписки, в таких группах для изменения состава группы или настроек отдельных серверов нет необходимости перезапускать nginx. Конфигурация доступна через модуль API (1.13.3).
До версии 1.13.3 конфигурация была доступна только через специальный location, в котором указана директива upstream_conf.
| Синтаксис: | state файл ; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.9.7.
В данный момент состояние ограничено списком серверов с их параметрами. Файл читается при парсинге конфигурации и обновляется каждый раз при изменении конфигурации группы. Изменение содержимого файла напрямую не рекомендуется. Директиву нельзя использовать совместно с директивой server.
| Синтаксис: | hash ключ [ consistent ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.7.2.
Задаёт для группы метод балансировки нагрузки, при котором запросы распределяются по серверам на основе IP-адресов клиентов. В качестве ключа для хэширования используются первые три октета IPv4-адреса клиента или IPv6-адрес клиента целиком. Метод гарантирует, что запросы одного и того же клиента будут всегда передаваться на один и тот же сервер. Если же этот сервер будет считаться недоступным, то запросы этого клиента будут передаваться на другой сервер. С большой долей вероятности это также будет один и тот же сервер.
IPv6-адреса поддерживаются начиная с версий 1.3.2 и 1.2.2.
| Синтаксис: | keepalive соединения ; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.1.4.
Задействует кэш соединений для группы серверов.
Параметр соединения устанавливает максимальное число неактивных постоянных соединений с серверами группы, которые будут сохраняться в кэше каждого рабочего процесса. При превышении этого числа наиболее давно не используемые соединения закрываются.
Следует особо отметить, что директива keepalive не ограничивает общее число соединений с серверами группы, которые рабочие процессы nginx могут открыть. Параметр соединения следует устанавливать достаточно консервативно, чтобы серверы группы по-прежнему могли обрабатывать новые входящие соединения.
Пример конфигурации группы серверов memcached с постоянными соединениями:
Для HTTP директиву proxy_http_version следует установить в “ 1.1 ”, а поле заголовка “Connection” — очистить:
Хоть это и не рекомендуется, но также возможно использование постоянных соединений с HTTP/1.0, путём передачи поля заголовка “Connection: Keep-Alive” серверу группы.
Для работы постоянных соединений с FastCGI-серверами потребуется включить директиву fastcgi_keep_conn:
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
| Синтаксис: | keepalive_requests число ; |
|---|---|
| Умолчание: | |
| Контекст: | upstream |
Эта директива появилась в версии 1.15.3.
Задаёт максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.
Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.
До версии 1.19.10 по умолчанию использовалось значение 100.
| Синтаксис: | keepalive_time время ; |
|---|---|
| Умолчание: | |
| Контекст: | upstream |
Эта директива появилась в версии 1.19.10.
Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках постоянного соединения. По достижении заданного времени соединение закрывается после обработки очередного запроса.
| Синтаксис: | keepalive_timeout таймаут ; |
|---|---|
| Умолчание: | |
| Контекст: | upstream |
Эта директива появилась в версии 1.15.3.
Задаёт таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.
Эта директива появилась в версии 1.9.2.
Позволяет проксировать запросы с проверкой подлинности NTLM. Соединение с сервером группы привязывается к клиентскому соединению как только клиент отправляет запрос, в заголовке которого есть поле “Authorization” со значением, начинающимся с “ Negotiate ” или “ NTLM ”. Последующие запросы клиента будут проксироваться через это же соединение с сервером группы, сохраняя контекст аутентификации.
Для работы проверки подлинности NTLM необходимо разрешить постоянные соединения с серверами группы. Директиву proxy_http_version следует установить в “ 1.1 ”, а поле заголовка “Connection” — очистить:
| Синтаксис: | least_conn; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версиях 1.3.1 и 1.2.2.
Задаёт для группы метод балансировки нагрузки, при котором запрос передаётся серверу с наименьшим числом активных соединений, с учётом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учётом их весов.
| Синтаксис: | least_time header | last_byte [ inflight ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.7.10.
Задаёт для группы метод балансировки нагрузки, при котором запрос передаётся серверу с наименьшими средним временем ответа и числом активных соединений с учётом весов серверов. Если подходит сразу несколько серверов, то они выбираются циклически (в режиме round-robin) с учётом их весов.
До версии 1.11.6 незавершённые запросы учитывались по умолчанию.
| Синтаксис: | queue число [ timeout = время ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.5.12.
По умолчанию параметр timeout равен 60 секундам.
| Синтаксис: | random [ two [ метод ]]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива появилась в версии 1.15.1.
Задаёт для группы метод балансировки нагрузки, при котором запрос передаётся случайно выбранному серверу, с учётом весов серверов.
Эта директива появилась в версии 1.17.5.
Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов в адреса, например:
Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта. Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.
По умолчанию nginx кэширует ответы, используя значение TTL из ответа. Необязательный параметр valid позволяет это переопределить:
Для предотвращения DNS-спуфинга рекомендуется использовать DNS-серверы в защищённой доверенной локальной сети.
| Синтаксис: | resolver_timeout время ; |
|---|---|
| Умолчание: | |
| Контекст: | upstream |
Эта директива появилась в версии 1.17.5.
Задаёт таймаут для преобразования имени в адрес, например:
Эта директива появилась в версии 1.5.7.
Включает режим привязки сеансов, в котором запросы клиента будут передаваться на один и тот же сервер группы. Доступны три метода:
При использовании метода cookie информация о назначенном сервере передаётся в HTTP-куке:
Запрос от клиента, ещё не привязанного к определённому серверу, передаётся на сервер, выбранный согласно настроенному методу балансировки. Дальнейшие запросы от этого клиента передаются на тот же сервер. Если назначенный сервер не может обработать запрос, выбирается новый сервер как если бы клиент не имел привязки к серверу.
Так как любой метод балансировки пытается равномерно распределить нагрузку, учитывая уже привязанные запросы, сервер с наибольшим количеством привязанных запросов имеет меньшую вероятность получить новые, не привязанные запросы.
Первый параметр задаёт имя куки, которую необходимо установить или проверить. Значением куки является MD5-хэш IP-адреса и порта (или пути UNIX-сокета) в шестнадцатеричном виде. Однако если указан параметр “ route ” директивы server, то значением куки будет значение параметра “ route ”:
Дополнительные параметры могут быть следующими:
Если пропущен тот или иной параметр, то соответствующего поля в куке не будет.
При использовании метода route проксируемый сервер назначает клиенту маршрут по получении первого запроса. Все последующие запросы от этого клиента будут содержать информацию о маршруте в куке или URI. Эта информация сравнивается с параметром “ route ” директивы server для идентификации сервера, на который следует проксировать запрос. Если параметр “ route ” не задан, то именем маршрута будет являться MD5-хэш IP-адреса и порта (или пути UNIX-сокета) в шестнадцатеричном виде. Если назначенный сервер не может обработать запрос, выбирается новый сервер согласно настроенному методу балансировки как если бы в запросе не было информации о маршруте.
Параметры метода route задают переменные, которые могут содержать информацию о маршруте. Первая непустая переменная используется для поиска соответствующего сервера.
В этом примере маршрут берётся из куки “ JSESSIONID ”, если она присутствует в запросе. В противном случае используется маршрут из URI.
При использовании метода learn (1.7.1) nginx анализирует ответы от вышестоящего сервера и запоминает начатые им сессии, которые обычно передаются в HTTP-куке.
В примере выше сервер группы создаёт сессию путём установки куки “ EXAMPLECOOKIE ” в своём ответе. Последующие запросы с этой кукой будут передаваться на этот же сервер. Если сервер не может обработать запрос, выбирается новый сервер как если бы клиент не имел привязки к серверу.
Параметры create и lookup задают переменные, в которых соответственно указывается способ создания новых и поиска существующих сессий. Оба параметра могут быть указаны больше одного раза (в этом случае используется первая непустая переменная).
Параметр header (1.13.1) позволяет создавать сессию сразу после получения заголовков ответа от сервера группы.
Параметр sync (1.13.8) разрешает синхронизацию данной зоны разделяемой памяти.
| Синтаксис: | sticky_cookie_insert имя [ expires= время ] [ domain= домен ] [ path= путь ]; |
|---|---|
| Умолчание: | — |
| Контекст: | upstream |
Эта директива устарела начиная с версии 1.5.7. Вместо неё следует использовать аналогичную директиву sticky с изменённым синтаксисом:
sticky cookie имя [ expires= время ] [ domain= домен ] [ path= путь ];
Встроенные переменные
Модуль ngx_http_upstream_module поддерживает следующие встроенные переменные:
Upstream nginx что это
Модуль ngx_http_upstream_module позволяет описывать группы серверов, которые могут использоваться в директивах proxy_pass, fastcgi_pass и memcached_pass.
Пример конфигурации
Директивы
Описывает группу серверов. Серверы могут слушать на разных портах. Кроме того, можно одновременно использовать серверы, слушающие на TCP- и UNIX-сокетах.
По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учётом весов серверов. В вышеприведённом примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы. Если при попытке работы с сервером произошла ошибка, то запрос будет передан следующему серверу, и так до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращён результат работы с последним сервером.
| синтаксис: | server адрес [ параметры ]; |
| умолчание: | — |
| контекст: | upstream |
Задаёт адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта, или в виде пути UNIX-сокета, который указывается после префикса “ unix: ”. Если порт не указан, используется порт 80. Доменное имя, которому соответствует несколько IP-адресов, задаёт сразу несколько серверов.
Могут быть заданы следующие параметры:
Задаёт для группы метод балансировки нагрузки, при котором запросы распределяются по серверам на основе IP-адресов клиентов. В качестве ключа для хэширования используются первые три октета IPv4-адреса клиента или IPv6-адрес клиента целиком. Метод гарантирует, что запросы одного и того же клиента будут всегда передаваться на один и тот же сервер. Если же этот сервер будет считаться неработающим, то запросы этого клиента будут передаваться на другой сервер. С большой долей вероятности это также будет один и тот же сервер.
IPv6-адреса поддерживаются начиная с версий 1.3.2 и 1.2.2.
| синтаксис: | keepalive соединения ; |
| умолчание: | — |
| контекст: | upstream |
Эта директива появилась в версии 1.1.4.
Задействует кэш соединений для группы серверов.
Параметр соединения устанавливает максимальное число неактивных постоянных соединений с серверами группы, которые будут сохраняться в кэше каждого рабочего процесса. При превышении этого числа наиболее давно не используемые соединения закрываются.
Следует особо отметить, что директива keepalive не ограничивает общее число соединений с серверами группы, которые рабочие процессы nginx могут открыть. Параметр соединения следует устанавливать достаточно консервативно для обеспечения возможности обработки серверами группы новых входящих соединений.
Пример конфигурации группы серверов memcached с постоянными соединениями:
Для HTTP директиву proxy_http_version следует установить в “ 1.1 ”, а поле заголовка “Connection” — очистить:
Хоть это и не рекомендуется, но также возможно использование постоянных соединений в HTTP/1.0, путём передачи поля заголовка “Connection: Keep-Alive” серверу группы.
Для работы постоянных соединений с FastCGI-серверами потребуется включить директиву fastcgi_keep_conn:
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
| синтаксис: | least_conn; |
| умолчание: | — |
| контекст: | upstream |
Эта директива появилась в версиях 1.3.1 и 1.2.2.
Задаёт для группы метод балансировки нагрузки, при котором запрос передаётся серверу с наименьшим числом активных соединений, с учётом весов серверов. Если подходит сразу несколько серверов, они выбираются циклически (в режиме round-robin) с учётом их весов.
Встроенные переменные
Модуль ngx_http_upstream_module поддерживает следующие встроенные переменные: