# Upstream Probe Реализует активные проверки работоспособности (health probes) для [Upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream). ## Пример конфигурации ```nginx server { listen ...; # ... proxy_pass backend; upstream_probe_timeout 1s; upstream_probe backend_probe port=12345 interval=5s test=$good essential fails=3 passes=3 max_response=512k mode=onfail "send=data:GET / HTTP/1.0\r\n\r\n"; } ``` #### NOTE Согласно спецификации RFC 2616 (HTTP/1.1) и RFC 9110 (HTTP Semantics), заголовки HTTP должны разделяться последовательностью CRLF (`\r\n`), а не просто `\n`. ## Директивы ### upstream_probe (PRO) | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe` имя [`port=`число] [`interval=`время] [`test=`условие] [`essential` [`persistent`]] [`fails=`число] [`passes=`число] [`max_response=`размер] [`mode=``always` | `idle` | `onfail`] [`udp`] [`send=`строка] [`ping`] [`ping_timeout=`время]; | |------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server | Задает активную проверку работоспособности серверов [апстрима](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream), указанного в директиве [proxy_pass](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-pass) в том же контексте `server`, где находится директива `upstream_probe`. Сервер проходит проверку, если запрос к нему успешно выполняется с учетом всех параметров самой директивы `upstream_probe` и всех параметров, влияющих на использование апстримов тем контекстом `server`, где она задана, в том числе директивы [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream). Чтобы использовать проверки, в апстриме необходима зона разделяемой памяти ([zone](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-zone)). Для одного апстрима можно определить несколько проверок. Могут быть заданы следующие параметры: | `имя` | Обязательное имя проверки. | |----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `port` | Альтернативный порт для запроса. | | `interval` | [Интервал](https://angie.software//angie/docs/configuration/configfile.md#syntax) между проверками.
По умолчанию — `5s`. | | `test` | Проверяемое при запросе условие; задается строкой из переменных.
Если результат подстановки всех переменных — `""` или `"0"`,
проверка не пройдена. | | `essential` | Если параметр задан, то изначально состояние сервера подлежит уточнению
и клиентские запросы не передаются ему, пока проверка не будет пройдена. | | `persistent` | Установка этого параметра требует сначала включить `essential`;
серверы с `persistent`, работавшие до
[перезагрузки конфигурации](https://angie.software//angie/docs/configuration/configfile.md#configfile-reloading),
начинают получать запросы без необходимости сначала пройти эту проверку. | | `fails` | Число последовательных неуспешных запросов,
при котором проверка считает сервер неработающим.
По умолчанию — 1. | | `passes` | Число последовательных успешных запросов,
при котором проверка считает сервер работающим.
По умолчанию — 1. | | `max_response` | Максимальный объем памяти для ответа. Если задано нулевое
[значение](https://angie.software//angie/docs/configuration/configfile.md#syntax), ожидание ответа отключается.
По умолчанию — `256k`. | | `mode` | Режим проверки в зависимости от работоспособности серверов:

- `always` — серверы проверяются независимо от состояния;
- `idle` — проверяются неработающие серверы, а также серверы,
где с последнего клиентского запроса прошло время `interval`.
- `onfail` — проверяются серверы только в неработающем состоянии.

По умолчанию — `always`. | | `udp` | Если параметр указан, используется протокол UDP.
По умолчанию для проверок используется TCP. | | `send` | Отправляемые для проверки данные: встроенные данные с префиксом `data:`
или путь к файлу (абсолютный или относительно `/usr/local/angie/`).

При использовании файла:

- [Рабочий процесс](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) открывает и читает
файл при каждом обращении; содержимое не сохраняется в памяти.
- Перезагрузка конфигурации при изменении файла не требуется;
новое содержимое будет прочитано при следующем обращении.
- Необходимые права доступа: `644` для файла,
`755` для директории.
- Обновляйте файлы командой перемещения (`mv`),
а не прямым редактированием. | | `ping` (PRO) | Использует ICMP echo запросы вместо TCP/UDP-проверок.
Требует сборки Angie с `--with-stream_upstream_probe_icmp`.
Несовместимо с `test`, `port`,
`udp` и `send`. | | `ping_timeout` (PRO) | Таймаут ожидания ICMP echo ответа.
По умолчанию — `1s`. | Пример: ```nginx upstream backend { zone backend 1m; server a.example.com; server b.example.com; } map $upstream_probe_response $good { ~200 "1"; default ""; } server { listen ...; # ... proxy_pass backend; upstream_probe_timeout 1s; upstream_probe backend_probe port=12345 interval=5s test=$good essential persistent fails=3 passes=3 max_response=512k mode=onfail "send=data:GET / HTTP/1.0\r\n\r\n"; } ``` Детали работы: - Изначально сервер не получает клиентские запросы, пока не пройдет *все* заданные для него проверки с параметром `essential` (пропуская помеченные как `persistent`, если конфигурация перезагружена и до этого сервер считался работающим). Если таких проверок нет, сервер считается работающим. - Сервер считается неработающим и не получает клиентские запросы, если *какая-либо* заданная для него проверка достигает своего порога `fails` или сам сервер достигает порога [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails). - Чтобы неработающий сервер снова мог считаться работающим, *все* заданные для него проверки должны достичь своего порога `passes`; после этого учитывается порог [max_fails](https://angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails). ### upstream_probe_timeout (PRO) | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe_timeout` время; | |------------------------------------------------------------------------------------------|-----------------------------------| | По умолчанию | `upstream_probe_timeout 50s;` | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server | Задает максимальное [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) бездействия установленного с сервером соединения для проверок, настроенных с помощью директивы [upstream_probe (PRO)](#s-u-upstream-probe); при превышении этого предела соединение будет закрыто. ## Встроенные переменные Модуль `stream_upstream` поддерживает следующие встроенные переменные: ### `$upstream_probe` (PRO) Имя активной сейчас проверки [upstream_probe](#s-u-upstream-probe). ### `$upstream_probe_response` (PRO) Содержимое ответа, полученного в ходе активной проверки [upstream_probe](#s-u-upstream-probe).