<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_upstream_hc_module"
        link="/ru/docs/http/ngx_http_upstream_hc_module.html"
        lang="ru"
        rev="5">

<section id="summary">

<para>
Модуль <literal>ngx_http_upstream_hc_module</literal>
позволяет активировать периодические проверки работоспособности серверов в
<link doc="ngx_http_upstream_module.xml" id="upstream">группе</link>,
указанной в содержащем location.
Группа должна находиться в
<link doc="ngx_http_upstream_module.xml" id="zone">зоне разделяемой памяти</link>.
</para>

<para>
Если проверка работоспособности была неуспешной,
то сервер признаётся неработоспособным.
Если для группы задано несколько проверок,
то при любой неуспешной проверке соответствующий сервер будет
считаться неработоспособным.
На неработоспособные серверы и серверы в состоянии “checking”
клиентские запросы передаваться не будут.
</para>

<para>
<note>
Обратите внимание, что при использовании проверок
большинство переменных имеют пустые значения.
</note>
</para>

<para>
<note>
Модуль доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;

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

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}
</example>
Каждому серверу группы <literal>backend</literal>
с интервалом в 5 секунд посылаются запросы “<literal>/</literal>”.
Если происходит ошибка или таймаут при работе с сервером, или
код ответа проксируемого сервера не равен
2xx или 3xx, проверка считается неуспешной и сервер
признаётся неработоспособным.
</para>

<para>
Проверки работоспособности могут тестировать код ответа,
наличие или отсутствие определённых полей заголовка и их значений,
а также содержимое тела ответа.
Тесты настраиваются отдельно при помощи директивы <link id="match"/>
и указываются в параметре <literal>match</literal>.
Например:
<example>
http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}
</example>
В такой конфигурации успешный ответ на проверочный запрос
должен иметь код 200, тип содержимого “<literal>text/html</literal>”
и “<literal>Welcome to nginx!</literal>” в теле ответа.
</para>

</section>


<section id="directives" name="Директивы">

<directive name="health_check">
<syntax>[<value>параметры</value>]</syntax>
<default/>
<context>location</context>

<para>
Активирует периодические проверки работоспособности серверов в
<link doc="ngx_http_upstream_module.xml" id="upstream">группе</link>,
указанной в содержащем location.
</para>

<para>
Могут быть заданы следующие необязательные параметры:
<list type="tag">

<tag-name id="health_check_interval">
<literal>interval</literal>=<value>время</value>
</tag-name>
<tag-desc>
задаёт интервал между двумя последовательными проверками,
по умолчанию 5 секунд.
</tag-desc>

<tag-name id="health_check_jitter">
<literal>jitter</literal>=<value>время</value>
</tag-name>
<tag-desc>
задаёт время, в пределах которого
случайным образом задерживается каждая проверка,
по умолчанию задержки нет.
</tag-desc>

<tag-name id="health_check_fails">
<literal>fails</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт число последовательных неуспешных проверок для определённого сервера,
после которых сервер будет считаться неработоспособным,
по умолчанию 1.
</tag-desc>

<tag-name id="health_check_passes">
<literal>passes</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт число последовательных успешных проверок для определённого сервера,
после которых сервер будет считаться работоспособным,
по умолчанию 1.
</tag-desc>

<tag-name id="health_check_uri">
<literal>uri</literal>=<value>uri</value>
</tag-name>
<tag-desc>
задаёт URI, используемый в запросах, проверяющих работоспособность,
по умолчанию “<literal>/</literal>”.
</tag-desc>

<tag-name id="health_check_mandatory">
<literal>mandatory</literal> [<literal>persistent</literal>]
</tag-name>
<tag-desc>
<para>
устанавливает исходное состояние “checking” для сервера
до завершения первой проверки работоспособности (1.11.7).
На серверы в состоянии “checking” клиентские запросы передаваться не будут.
Если параметр не указан,
то исходно сервер будет считаться работоспособным.
</para>

<para id="health_check_persistent">
Параметр <literal>persistent</literal> (1.19.7)
устанавливает исходное состояние “up” для сервера после перезагрузки nginx
в случае, если до перезагрузки сервер считался работоспособным.
</para>
</tag-desc>

<tag-name id="health_check_match">
<literal>match</literal>=<value>имя</value>
</tag-name>
<tag-desc>
указывает на блок <literal>match</literal> с условиями, которым должен
удовлетворять ответ, чтобы результат проверки считался успешным.
По умолчанию код ответа должен быть 2xx или 3xx.
</tag-desc>

<tag-name id="health_check_port">
<literal>port</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт порт, используемый при подключении к серверу
для проверки его работоспособности (1.9.7).
По умолчанию совпадает с портом
<link doc="ngx_http_upstream_module.xml" id="server">сервера</link>.
</tag-desc>

<tag-name id="health_check_grpc">
<literal>type</literal>=<literal>grpc</literal>
[<literal>grpc_service</literal>=<value>имя</value>]
[<literal>grpc_status</literal>=<value>код</value>]
</tag-name>
<tag-desc>
активирует периодические
<link url="https://github.com/grpc/grpc/blob/master/doc/health-checking.md#grpc-health-checking-protocol">проверки
работоспособности</link> gRPC-сервера
или службы gRPC, указанной при помощи необязательного
параметра <literal>grpc_service</literal> (1.19.5).
Если сервер не поддерживает протокол проверки работоспособности gRPC,
то можно использовать необязательный параметр <literal>grpc_status</literal>
для указания
<link url="https://github.com/grpc/grpc/blob/master/doc/statuscodes.md#status-codes-and-their-use-in-grpc">статуса</link>
(например
статус “<literal>12</literal>” / “<literal>UNIMPLEMENTED</literal>”)
при получении которого сервер признаётся работоспособным:
<example>
health_check mandatory type=grpc grpc_status=12;
</example>
Параметр <literal>type</literal>=<literal>grpc</literal>
должен быть указан после остальных параметров директивы,
<literal>grpc_service</literal> и <literal>grpc_status</literal>
должны быть указаны после <literal>type</literal>=<literal>grpc</literal>.
Параметр несовместим с параметрами
<link id="health_check_uri"><literal>uri</literal></link> и
<link id="health_check_match"><literal>match</literal></link>.
</tag-desc>

</list>
</para>

</directive>


<directive name="match">
<syntax block="yes"><value>имя</value></syntax>
<default/>
<context>http</context>

<para>
Задаёт именованный набор тестов для анализа ответов
на запросы проверки работоспособности.
</para>

<para>
В ответе могут быть протестированы следующие объекты:
<list type="tag">

<tag-name><literal>status 200;</literal></tag-name>
<tag-desc>код ответа равен 200</tag-desc>

<tag-name><literal>status ! 500;</literal></tag-name>
<tag-desc>код ответа не равен 500</tag-desc>

<tag-name><literal>status 200 204;</literal></tag-name>
<tag-desc>код ответа равен 200 или 204</tag-desc>

<tag-name><literal>status ! 301 302;</literal></tag-name>
<tag-desc>код ответа не равен ни 301, ни 302</tag-desc>

<tag-name><literal>status 200-399;</literal></tag-name>
<tag-desc>код ответа находится в диапазоне от 200 до 399</tag-desc>

<tag-name><literal>status ! 400-599;</literal></tag-name>
<tag-desc>код ответа находится вне диапазона от 400 до 599</tag-desc>

<tag-name><literal>status 301-303 307;</literal></tag-name>
<tag-desc>код ответа равен 301, 302, 303 или 307</tag-desc>

</list>

<list type="tag">

<tag-name><literal>header Content-Type = text/html;</literal></tag-name>
<tag-desc>
заголовок содержит <header>Content-Type</header>
со значением <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Content-Type != text/html;</literal></tag-name>
<tag-desc>
заголовок содержит <header>Content-Type</header>
со значением, отличным от <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Connection ~ close;</literal></tag-name>
<tag-desc>
заголовок содержит <header>Connection</header>
со значением, совпадающим с регулярным выражением <literal>close</literal>
</tag-desc>

<tag-name><literal>header Connection !~ close;</literal></tag-name>
<tag-desc>
заголовок содержит <header>Connection</header>
со значением, не совпадающим с регулярным выражением <literal>close</literal>
</tag-desc>

<tag-name><literal>header Host;</literal></tag-name>
<tag-desc>заголовок содержит <header>Host</header></tag-desc>

<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
<tag-desc>заголовок не содержит <header>X-Accel-Redirect</header></tag-desc>

</list>

<list type="tag">

<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
тело ответа совпадает с регулярным выражением
“<literal>Welcome to nginx!</literal>”
</tag-desc>

<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
тело ответа не совпадает с регулярным выражением
“<literal>Welcome to nginx!</literal>”
</tag-desc>

</list>

<list type="tag">

<tag-name id="match_require"><literal>require</literal>
                             <value>$переменная</value>
                             <literal>...;</literal></tag-name>
<tag-desc>
все указанные переменные непустые и не равны “0” (1.15.9).
</tag-desc>

</list>
</para>

<para>
Если задано несколько тестов,
то ответ должен удовлетворять всем тестам.
<note>
Проверяются только первые 256 Кбайт тела ответа.
</note>
</para>

<para>
Примеры:
<example>
# код ответа 200, тип содержимого "text/html"
# и тело ответа содержит "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}
</example>

<example>
# код ответа не равен 301, 302, 303 и 307 и заголовок не содержит "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}
</example>

<example>
# код ответа успешный и сервер не в сервисном режиме
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}
</example>

<example>
# код ответа равен 200 или 204
map $upstream_status $good_status {
    200     1;
    204     1;
}

match server_ok {
    require $good_status;
}
</example>

</para>

</directive>

</section>

</module>