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.2, выпущенную 9 апреля 2026 года.

---

Библиотека проверки состояния для 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.2 (09-апр-2026)

• Fix(active-checks): используйте HTTP/1.1 для проб здоровья с автоматической согласованием версии #176

3.1.1 (19-ноя-2025)

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

3.1.0 (19-июн-2024)

• Feat: удалите проверку версии resty.events #162

3.0.2 (16-май-2024)

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

3.0.1 (22-дек-2023)

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

3.0.0 (12-окт-2023)

• Perf: оптимизируйте, локализовав некоторые функции #92 (backport)
• Fix: генерируйте свежие значения по умолчанию для http_statuses внутри new() #83 (backport)

2.0.0 (22-сен-2020)

Примечание: Изменения в этой версии были отменены для текущей и будущей разработки. Ниже вы можете увидеть его changelog, но будьте внимательны, что эти изменения могут отсутствовать в 3.y.z, если они не указаны явно в 3.y.z, 1.6.3 или предыдущих релизах. Читайте подробнее в: выпуск 3.0.0 (#142) и chore(*): выравнивание ветки master к выпуску 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
• feature: добавлена поддержка https_sni #49
• fix: правильно регистрируйте номера строк, используя хвостовые вызовы #29
• fix: при отсутствии имени хоста используйте IP #48
• fix: makefile; make install
• feature: добавлено поле версии состояния #54
• feature: добавьте заголовки для запроса пробы #54
• fix: выходите раньше при перезагрузке во время пробы #47
• fix: предотвратите, чтобы список целей был nil из-за асинхронного поведения #44
• fix: замените таймер и блокировки на уровне узла на resty-timer, чтобы предотвратить пропуски интервалов #59
• change: добавлено дополнительное логирование при публикации событий #25
• fix: не исчерпывайте таймеры во время init/init_worker при добавлении большого количества целей #57
• fix: не вызывайте на таблице модуля, а используйте метод для блокировок. Также в #57

1.6.3 (06-сен-2023)

• Feature: добавлена поддержка https_sni #49 (backport)
• Fix: используйте API OpenResty для mTLS #99 (backport)

1.6.2 (17-ноя-2022)

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

1.6.1 (25-июл-2022)

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

1.6.0 (27-июн-2022)

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

1.5.3 (14-ноя-2022)

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

1.5.2 (07-июл-2022)

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

1.5.1 (23-мар-2022)

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

1.5.0 (09-фев-2022)

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

1.4.3 (31-мар-2022)

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

1.4.2 (29-июн-2021)

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

1.4.1 (17-фев-2021)

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

1.4.0 (07-янв-2021)

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

1.3.0 (17-июн-2020)

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

1.2.0 (13-фев-2020)

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

1.1.2 (19-дек-2019)

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

1.1.1 (14-ноя-2019)

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

1.1.0 (30-сен-2019)

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

1.0.0 (05-июл-2019)

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

0.6.1 (04-апр-2019)

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

0.6.0 (26-сен-2018)

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

0.5.0 (25-июл-2018)

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

0.4.2 (23-май-2018)

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

0.4.1 (21-май-2018)

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

0.4.0 (20-мар-2018)

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

0.3.0 (18-дек-2017)

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

0.2.0 (30-ноя-2017)

• Добавляет set_target_status

0.1.0 (27-ноя-2017) Первоначальный выпуск

• Первоначальная загрузка

GitHub

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