healthcheck: Библиотека проверки состояния для nginx-module-lua для проверки статуса upstream-сервиса

Установка

Если вы еще не настроили подписку на RPM-репозиторий, зарегистрируйтесь. Затем вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-healthcheck

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-healthcheck

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-healthcheck v3.1.1, выпущенный 19 ноября 2025 года.

latest version latest luarocks version

Библиотека проверки состояния для OpenResty.

Синопсис

http {
    lua_shared_dict test_shm 8m;
    lua_shared_dict my_worker_events 8m;
    init_worker_by_lua_block {

        local we = require "resty.worker.events"
        local ok, err = we.configure({
            shm = "my_worker_events",
            interval = 0.1
        })
        if not ok then
            ngx.log(ngx.ERR, "не удалось настроить события рабочего процесса: ", err)
            return
        end

        local healthcheck = require("resty.healthcheck")
        local checker = healthcheck.new({
            name = "testing",
            shm_name = "test_shm",
            checks = {
                active = {
                    type = "https",
                    http_path = "/status",
                    healthy  = {
                        interval = 2,
                        successes = 1,
                    },
                    unhealthy  = {
                        interval = 1,
                        http_failures = 2,
                    }
                },
            }
        })

        local ok, err = checker:add_target("127.0.0.1", 8080, "example.com", false)

        local handler = function(target, eventname, sourcename, pid)
            ngx.log(ngx.DEBUG,"Событие от: ", sourcename)
            if eventname == checker.events.remove
                -- цель была удалена
                ngx.log(ngx.DEBUG,"Цель удалена: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname == checker.events.healthy
                -- цель изменила состояние или была добавлена
                ngx.log(ngx.DEBUG,"Цель переключена на здоровую: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname ==  checker.events.unhealthy
                -- цель изменила состояние или была добавлена
                ngx.log(ngx.DEBUG,"Цель переключена на нездоровую: ",
                    target.ip, ":", target.port, " ", target.hostname)
            else
                -- неизвестное событие
            end
        end
    }
}

Описание

Эта библиотека поддерживает выполнение активных и пассивных проверок состояния на произвольных хостах.

Управление библиотекой осуществляется через ее программный API. Потребление ее событий происходит через библиотеку lua-resty-worker-events.

Цели добавляются с помощью checker:add_target(host, port). Изменения в статусе ("healthy" или "unhealthy") транслируются через worker-events.

Активные проверки выполняются в фоновом режиме на основе заданных интервалов таймера.

Для пассивных проверок состояния библиотека получает явные уведомления через свой программный API, используя такие функции, как checker:report_http_status(host, port, status).

Смотрите онлайн-документацию LDoc для полного API.

История

Версионирование строго основано на Semantic Versioning

Выпуск новых версий:

обновите changelog ниже (PR должны быть объединены, включая запись в changelog)
на основе changelog определите новую версию SemVer
создайте новый rockspec
отрендерите документацию с помощью ldoc (не делайте это в рамках PR)
закоммитьте как "release x.x.x" (не включайте ревизию rockspec)
тегируйте коммит как "x.x.x" (не включайте ревизию rockspec)
отправьте коммит и тег
загрузите rock в luarocks: luarocks upload rockspecs/[name] --api-key=abc

3.1.1 (19-Nov-2025)

Исправление: изменить заголовки по умолчанию на пустую таблицу вместо массива, чтобы убрать уведомление о депрекации #174

3.1.0 (19-Jun-2024)

Функция: удалить проверку версии resty.events #162

3.0.2 (16-May-2024)

Исправление: избежать создания нескольких таймеров для выполнения одной и той же активной проверки #157

3.0.1 (22-Dec-2023)

Исправление: исправить логику очистки задержки, когда было запущено несколько healthchecker #146

3.0.0 (12-Oct-2023)

Производительность: оптимизация за счет локализации некоторых функций #92 (backport)
Исправление: Генерация свежих http_statuses по умолчанию в new() #83 (backport)

2.0.0 (22-Sep-2020)

Примечание: Изменения в этой версии были отклонены от текущей и будущей разработки. Ниже вы можете увидеть его changelog, но имейте в виду, что эти изменения могут отсутствовать в 3.y.z, если они не указаны явно в 3.y.z, 1.6.3 или предыдущих релизах. Читайте больше на: выпуск 3.0.0 (#142) и chore(*): выравнивание основной ветки к выпуску 3.0.0 (#144)

BREAKING: резервное копирование для устаревшего верхнего уровня поля type теперь удалено (устарело с 0.5.0) #56

BREAKING: Обновление зависимости lua-resty-worker-events до 2.0.0. Это делает многие API в этой библиотеке асинхронными, так как события рабочего процесса post и post_local больше не будут автоматически вызывать poll на работающем рабочем процессе, для получения дополнительной информации смотрите: https://github.com/Kong/lua-resty-worker-events#200-16-september-2020

BREAKING: tcp_failures больше не могут быть 0 при http(s) проверках (если http(s)_failures также не установлены в 0) #55

функция: Добавлена поддержка https_sni #49

исправление: правильно регистрировать номера строк, используя хвостовые вызовы #29

исправление: при отсутствии имени хоста использовать IP #48

исправление: makefile; make install

функция: добавлено поле версии статуса #54

функция: добавлены заголовки для запроса проверки #54

исправление: преждевременный выход при перезагрузке во время проверки #47

исправление: предотвратить, чтобы список целей не был nil из-за асинхронного поведения #44

исправление: заменить таймер и блокировки на уровне узла на resty-timer, чтобы предотвратить пропуски интервалов #59

изменение: добавлено дополнительное логирование при публикации событий #25

исправление: не исчерпывать таймеры во время init/init_worker при добавлении большого количества целей #57

исправление: не вызывать на таблице модуля, а использовать метод для блокировок. Также в #57

1.6.3 (06-Sep-2023)

Функция: Добавлена поддержка https_sni #49 (backport)
Исправление: Использовать OpenResty API для mTLS #99 (backport)

1.6.2 (17-Nov-2022)

Исправление: избежать вызова событий рабочего процесса для новых целей, которые были помечены для задержанного удаления, т.е. цели, которые уже существуют в памяти, нуждаются только в очистке флага удаления при добавлении обратно. #122

1.6.1 (25-Jul-2022)

Исправление: улучшения для обеспечения надлежащей защиты общих ресурсов, чтобы избежать условий гонки и четко сообщать о состояниях отказа. #112, #113, #114.
Исправление: уменьшить частоту проверки неиспользуемых целей, сокращая количество создаваемых блокировок. #116
Исправление: принимать любой lua-resty-events релиз 0.1.x. #118

1.6.0 (27-Jun-2022)

Функция: ввести поддержку модуля lua-resty-events в дополнение к поддержке lua-resty-worker-events. С этим дополнением пакет lua-resty-healthcheck больше не требует конкретного модуля для совместного использования событий, но вам все равно нужно предоставить либо lua-resty-worker-events, либо lua-resty-events. #105
Изменение: если доступно, lua-resty-healthcheck теперь использует string.buffer, новый API сериализации LuaJIT. Если он недоступен, lua-resty-healthcheck возвращается к cjson. #109

1.5.3 (14-Nov-2022)

Исправление: избежать вызова событий рабочего процесса для новых целей, которые были помечены для задержанного удаления, т.е. цели, которые уже существуют в памяти, нуждаются только в очистке флага удаления при добавлении обратно. #121

1.5.2 (07-Jul-2022)

Улучшенное управление режимами отказа resty.lock, добавление дополнительных проверок для обеспечения удержания блокировки перед выполнением критического кода и улучшение решения о том, следует ли повторять функцию после тайм-аута при попытке захватить блокировку. #113
Увеличено логирование для сбоев заблокированных функций. #114
Частота очистки удаленных целей была снижена, что сократило количество создаваемых блокировок за короткий период. #116

1.5.1 (23-Mar-2022)

Исправление: избежать нарушения активных проверок состояния при добавлении или удалении целей. #93

1.5.0 (09-Feb-2022)

Новый параметр checks.active.headers поддерживает один или несколько списков значений, индексированных по имени заголовка. #87
Ввести функцию dealyed_clear(), используемую для удаления адресов после временного интервала. Эта функция может быть использована, когда адрес удаляется, но может быть добавлен снова до истечения интервала, сохраняя его статус здоровья. #88

1.4.3 (31-Mar-2022)

Исправление: избежать нарушения активных проверок состояния при добавлении или удалении целей. #100

1.4.2 (29-Jun-2021)

Исправление: предотвратить планирование новых активных проверок во время выполнения проверки состояния. #72
Исправление: удалить наблюдатель событий при остановке активной проверки состояния. #74; исправляет проблему Kong #7406

1.4.1 (17-Feb-2021)

Исправление: убедиться, что один рабочий процесс будет активно проверять статусы хостов. #67

1.4.0 (07-Jan-2021)

Использовать один таймер для активной проверки состояния целей. Это уменьшает количество таймеров, используемых проверками состояния, так как они раньше использовали два таймера на каждую цель. #62

1.3.0 (17-Jun-2020)

Добавлена поддержка mTLS для активных проверок состояния. Эта функция может быть использована, добавляя поля ssl_cert и ssl_key, с сертификатом и ключом соответственно, при создании нового объекта проверки состояния. #41

1.2.0 (13-Feb-2020)

Добавляет set_all_target_statuses_for_hostname, который устанавливает статусы для всех записей с данным именем хоста сразу.

1.1.2 (19-Dec-2019)

Исправление: когда API ngx.sleep недоступен (например, на этапе логирования), невозможно заблокировать с помощью lua-resty-lock, и любая функция, которая требует эксклюзивного доступа, будет завершаться с ошибкой. Это исправление добавляет метод повторной попытки, который запускает новый легкий поток, который имеет доступ к ngx.sleep, чтобы заблокировать критический путь. #37;

1.1.1 (14-Nov-2019)

Исправление: завершение, когда невозможно получить эксклюзивный доступ к списку целей. Это исправление предотвращает попадание рабочих процессов в несогласованное состояние. #34;

1.1.0 (30-Sep-2019)

Добавлена поддержка установки пользовательского заголовка Host, который будет использоваться для активных проверок.
Исправление: журналировать ошибку при сбое SSL Handshake #28;

1.0.0 (05-Jul-2019)

BREAKING: все функции API, связанные с хостами, теперь требуют аргумент hostname. Таким образом, разные имена хостов, слушающие на одной и той же комбинации IP и портов, не будут влиять друг на друга.
Исправление: исправить отчет о успехах активной TCP-пробы #20; исправляет проблему #19

0.6.1 (04-Apr-2019)

Исправление: настройка обратного вызова событий только после загрузки списка целей #18; исправляет проблему Kong #4453

0.6.0 (26-Sep-2018)

Введение поля checks.active.https_verify_certificate. По умолчанию оно равно true; установка его в false отключает проверку сертификата в активных проверках состояния по HTTPS.

0.5.0 (25-Jul-2018)

Добавлена поддержка https -- спасибо @gaetanfl за PR!
Введение отдельных полей checks.active.type и checks.passive.type; верхнее поле type по-прежнему поддерживается как резервное, но теперь устарело.

0.4.2 (23-May-2018)

Исправление заголовка Host в активных проверках состояния

0.4.1 (21-May-2018)

Исправление внутреннего управления счетчиками проверок состояния

0.4.0 (20-Mar-2018)

Исправление установки значений по умолчанию в http_statuses
Проверка типа и границ для таблицы checks

0.3.0 (18-Dec-2017)

Отключение отдельных проверок, устанавливая их счетчики в 0

0.2.0 (30-Nov-2017)

Добавляет set_target_status

0.1.0 (27-Nov-2017) Начальный выпуск

Начальная загрузка

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-healthcheck.