Модуль ngx_http_upstream_hc

Модуль ngx_http_upstream_hc_module

Пример конфигурации
Директивы
health_check
match

Модуль ngx_http_upstream_hc_module позволяет активировать периодические проверки работоспособности серверов в группе, указанной в содержащем location. Группа должна находиться в зоне разделяемой памяти.

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

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

Модуль доступен как часть коммерческой подписки.

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

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;
    }
}

Каждому серверу группы backend с интервалом в 5 секунд посылаются запросы “/”. Если происходит ошибка или таймаут при работе с сервером, или код ответа проксируемого сервера не равен 2xx или 3xx, проверка считается неуспешной и сервер признаётся неработоспособным.

Проверки работоспособности могут тестировать код ответа, наличие или отсутствие определённых полей заголовка и их значений, а также содержимое тела ответа. Тесты настраиваются отдельно при помощи директивы match и указываются в параметре match. Например:

http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}

В такой конфигурации успешный ответ на проверочный запрос должен иметь код 200, тип содержимого “text/html” и “Welcome to nginx!” в теле ответа.

Директивы

Синтаксис:	`health_check [параметры];`
Умолчание:	—
Контекст:	`location`

Активирует периодические проверки работоспособности серверов в группе, указанной в содержащем location.

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

interval=время

задаёт интервал между двумя последовательными проверками, по умолчанию 5 секунд.

jitter=время

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

fails=число

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

passes=число

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

uri=uri

задаёт URI, используемый в запросах, проверяющих работоспособность, по умолчанию “/”.

mandatory [persistent]

устанавливает исходное состояние “checking” для сервера до завершения первой проверки работоспособности (1.11.7). На серверы в состоянии “checking” клиентские запросы передаваться не будут. Если параметр не указан, то исходно сервер будет считаться работоспособным.

Параметр persistent (1.19.7) устанавливает исходное состояние “up” для сервера после перезагрузки nginx в случае, если до перезагрузки сервер считался работоспособным.

match=имя

указывает на блок match с условиями, которым должен удовлетворять ответ, чтобы результат проверки считался успешным. По умолчанию код ответа должен быть 2xx или 3xx.

port=число

задаёт порт, используемый при подключении к серверу для проверки его работоспособности (1.9.7). По умолчанию совпадает с портом сервера.

type=grpc [grpc_service=имя] [grpc_status=код]

активирует периодические проверки работоспособности gRPC-сервера или службы gRPC, указанной при помощи необязательного параметра grpc_service (1.19.5). Если сервер не поддерживает протокол проверки работоспособности gRPC, то можно использовать необязательный параметр grpc_status для указания статуса (например статус “12” / “UNIMPLEMENTED”) при получении которого сервер признаётся работоспособным:

health_check mandatory type=grpc grpc_status=12;

Параметр type=grpc должен быть указан после остальных параметров директивы, grpc_service и grpc_status должны быть указаны после type=grpc. Параметр несовместим с параметрами uri и match.

keepalive_time=время

включает keepalive соединения в проверках работоспособности и задаёт время, в течение которого могут обрабатываться запросы в рамках keepalive соединения (1.21.7). По умолчанию keepalive соединения выключены.

Синтаксис:	`match имя { ... }`
Умолчание:	—
Контекст:	`http`

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

В ответе могут быть протестированы следующие объекты:

status 200;: код ответа равен 200
status ! 500;: код ответа не равен 500
status 200 204;: код ответа равен 200 или 204
status ! 301 302;: код ответа не равен ни 301, ни 302
status 200-399;: код ответа находится в диапазоне от 200 до 399
status ! 400-599;: код ответа находится вне диапазона от 400 до 599
status 301-303 307;: код ответа равен 301, 302, 303 или 307

header Content-Type = text/html;: заголовок содержит “Content-Type” со значением text/html
header Content-Type != text/html;: заголовок содержит “Content-Type” со значением, отличным от text/html
header Connection ~ close;: заголовок содержит “Connection” со значением, совпадающим с регулярным выражением close
header Connection !~ close;: заголовок содержит “Connection” со значением, не совпадающим с регулярным выражением close
header Host;: заголовок содержит “Host”
header ! X-Accel-Redirect;: заголовок не содержит “X-Accel-Redirect”

body ~ "Welcome to nginx!";: тело ответа совпадает с регулярным выражением “Welcome to nginx!”
body !~ "Welcome to nginx!";: тело ответа не совпадает с регулярным выражением “Welcome to nginx!”

require $переменная ...;: все указанные переменные непустые и не равны “0” (1.15.9).

Если задано несколько тестов, то ответ должен удовлетворять всем тестам.

Проверяются только первые 256 Кбайт тела ответа.

Примеры:

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

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

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

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

match server_ok {
    require $good_status;
}