Saltar a contenido

healthcheck: Biblioteca de verificación de salud para nginx-module-lua para validar el estado del servicio upstream

Instalación

Si no has configurado la suscripción al repositorio RPM, regístrate. Luego puedes proceder con los siguientes pasos.

CentOS/RHEL 7 o 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

Para usar esta biblioteca Lua con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-healthcheck v3.1.2 lanzado el 09 de abril de 2026.

última versión última versión de luarocks rama principal Licencia Twitter Follow

Una biblioteca de verificación de salud para OpenResty.

Sinopsis

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, "falló al configurar eventos del trabajador: ", 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,"Evento de: ", sourcename)
            if eventname == checker.events.remove
                -- un objetivo fue eliminado
                ngx.log(ngx.DEBUG,"Objetivo eliminado: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname == checker.events.healthy
                -- el objetivo cambió de estado, o fue agregado
                ngx.log(ngx.DEBUG,"Objetivo cambiado a saludable: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname ==  checker.events.unhealthy
                -- el objetivo cambió de estado, o fue agregado
                ngx.log(ngx.DEBUG,"Objetivo cambiado a no saludable: ",
                    target.ip, ":", target.port, " ", target.hostname)
            else
                -- evento desconocido
            end
        end
    }
}

Descripción

Esta biblioteca admite la realización de verificaciones de salud activas y pasivas en hosts arbitrarios.

El control de la biblioteca se realiza a través de su API programática. El consumo de sus eventos se realiza a través de la biblioteca lua-resty-worker-events.

Los objetivos se agregan usando checker:add_target(host, port). Los cambios en el estado ("saludable" o "no saludable") se transmiten a través de eventos de trabajador.

Las verificaciones activas se ejecutan en segundo plano según los intervalos de temporizador especificados.

Para las verificaciones de salud pasivas, la biblioteca recibe notificaciones explícitas a través de su API programática utilizando funciones como checker:report_http_status(host, port, status).

Consulta la documentación LDoc en línea para la API completa.

Historia

El versionado se basa estrictamente en Semantic Versioning

Lanzando nuevas versiones:

  • actualizar el changelog a continuación (los PR deben ser fusionados incluyendo una entrada en el changelog)
  • basado en el changelog determinar la nueva versión SemVer
  • crear un nuevo rockspec
  • renderizar la documentación usando ldoc (no hacer esto dentro de PR)
  • confirmar como "release x.x.x" (no incluir la revisión del rockspec)
  • etiquetar el commit con "x.x.x" (no incluir la revisión del rockspec)
  • empujar el commit y la etiqueta
  • subir el rock a luarocks: luarocks upload rockspecs/[name] --api-key=abc

3.1.2 (09-Abr-2026)

  • Fix(active-checks): usar HTTP/1.1 para las sondas de verificación de salud con negociación automática de versión #176

3.1.1 (19-Nov-2025)

  • Fix: cambiar los encabezados predeterminados a una tabla vacía en lugar de un array para eliminar la notificación de desaprobación #174

3.1.0 (19-Jun-2024)

  • Feat: eliminar la verificación de versión de resty.events #162

3.0.2 (16-May-2024)

  • Fix: evitar crear múltiples temporizadores para ejecutar la misma verificación activa #157

3.0.1 (22-Dic-2023)

  • Fix: corregir la lógica de limpieza de retraso cuando se iniciaron múltiples verificadores de salud #146

3.0.0 (12-Oct-2023)

  • Perf: optimizar localizando algunas funciones #92 (backport)
  • Fix: Generar nuevos http_statuses predeterminados dentro de new() #83 (backport)

2.0.0 (22-Sep-2020)

Nota: Los cambios en esta versión han sido descartados del desarrollo actual y futuro. A continuación, puedes ver su changelog, pero ten en cuenta que estos cambios pueden no estar presentes en 3.y.z a menos que se indiquen explícitamente en 3.y.z, 1.6.3 o versiones anteriores. Lee más en: release 3.0.0 (#142) y chore(*): realinear la rama principal a la versión 3.0.0 (#144)

  • BREAKING: el fallback para el campo de nivel superior type ahora ha sido eliminado (desaprobado desde 0.5.0) #56
  • BREAKING: Aumentar la dependencia de lua-resty-worker-events a 2.0.0. Esto hace que muchas de las API en esta biblioteca sean asíncronas, ya que los eventos del trabajador post y post_local ya no llamarán automáticamente a poll en un trabajador en ejecución, para más información, consulta: https://github.com/Kong/lua-resty-worker-events#200-16-september-2020
  • BREAKING: tcp_failures ya no puede ser 0 en verificaciones http(s) (a menos que http(s)_failures también se establezcan en 0) #55
  • feature: Agregado soporte para https_sni #49
  • fix: registrar correctamente los números de línea utilizando llamadas de cola #29
  • fix: cuando no se proporciona un nombre de host, usar IP #48
  • fix: makefile; make install
  • feature: agregado un campo de versión de estado #54
  • feature: agregar encabezados para la solicitud de sondeo #54
  • fix: salir temprano al recargar durante un sondeo #47
  • fix: prevenir que la lista de objetivos sea nil, debido al comportamiento asíncrono #44
  • fix: reemplazar temporizador y bloqueos a nivel de nodo con resty-timer, para prevenir saltos de intervalo #59
  • change: agregar registro adicional al publicar eventos #25
  • fix: no quedarse sin temporizadores durante init/init_worker al agregar una gran cantidad de objetivos #57
  • fix: no llamar en la tabla del módulo, sino usar un método para bloqueos. También en #57

1.6.3 (06-Sep-2023)

  • Feature: Agregado soporte para https_sni #49 (backport)
  • Fix: Usar la API de OpenResty para mTLS #99 (backport)

1.6.2 (17-Nov-2022)

  • Fix: evitar generar eventos de trabajador para nuevos objetivos que fueron marcados para eliminación retrasada, es decir, los objetivos que ya existen en memoria solo necesitan que se limpie la bandera de eliminación al ser agregados nuevamente. #122

1.6.1 (25-Jul-2022)

  • Fix: mejoras para asegurar la correcta protección de recursos compartidos para evitar condiciones de carrera y reportar claramente los estados de fallo. #112, #113, #114.
  • Fix: reducir la frecuencia de verificación de objetivos no utilizados, reduciendo el número de bloqueos creados. #116
  • Fix: aceptar cualquier liberación de lua-resty-events 0.1.x. #118

1.6.0 (27-Jun-2022)

  • Feature: introducir soporte para el módulo lua-resty-events además del soporte para lua-resty-worker-events. Con esta adición, el paquete lua-resty-healthcheck de luarocks ya no requiere un módulo de compartición de eventos específico, pero aún se requiere proporcionar ya sea lua-resty-worker-events o lua-resty-events. #105
  • Change: si está disponible, lua-resty-healthcheck ahora usa string.buffer, la nueva API de serialización de LuaJIT. Si no está disponible, lua-resty-healthcheck vuelve a cjson. #109

1.5.3 (14-Nov-2022)

  • Fix: evitar generar eventos de trabajador para nuevos objetivos que fueron marcados para eliminación retrasada, es decir, los objetivos que ya existen en memoria solo necesitan que se limpie la bandera de eliminación al ser agregados nuevamente. #121

1.5.2 (07-Jul-2022)

  • Mejor manejo de los modos de fallo de resty.lock, añadiendo más verificaciones para asegurar que el bloqueo se mantenga antes de ejecutar código crítico, y mejorando la decisión sobre si una función debe ser reintentada después de un tiempo de espera al intentar adquirir un bloqueo. #113
  • Aumento del registro para fallos de funciones bloqueadas. #114
  • La frecuencia de limpieza de objetivos eliminados se redujo, disminuyendo el número de bloqueos creados en un corto período. #116

1.5.1 (23-Mar-2022)

  • Fix: evitar romper las verificaciones de salud activas al agregar o eliminar objetivos. #93

1.5.0 (09-Feb-2022)

  • Nueva opción checks.active.headers admite una o más listas de valores indexados por nombre de encabezado. #87
  • Introducir la función dealyed_clear(), utilizada para eliminar direcciones después de un intervalo de tiempo. Esta función puede ser utilizada cuando una dirección está siendo eliminada pero puede ser agregada nuevamente antes de que expire el intervalo, manteniendo su estado de salud. #88

1.4.3 (31-Mar-2022)

  • Fix: evitar romper las verificaciones de salud activas al agregar o eliminar objetivos. #100

1.4.2 (29-Jun-2021)

  • Fix: prevenir que se programen nuevas verificaciones activas mientras se está ejecutando una verificación de salud. #72
  • Fix: eliminar el observador de eventos al detener una verificación de salud activa. #74; corrige el problema de Kong #7406

1.4.1 (17-Feb-2021)

  • Fix: asegurarse de que un solo trabajador verifique activamente los estados de los hosts. #67

1.4.0 (07-Ene-2021)

  • Usar un solo temporizador para verificar activamente los objetivos de salud. Esto reduce el número de temporizadores utilizados por los verificadores de salud, ya que solían usar dos temporizadores por cada objetivo. #62

1.3.0 (17-Jun-2020)

  • Agrega soporte para mTLS a las verificaciones de salud activas. Esta función puede ser utilizada añadiendo los campos ssl_cert y ssl_key, con el certificado y la clave respectivamente, al crear un nuevo objeto de verificación de salud. #41

1.2.0 (13-Feb-2020)

  • Agrega set_all_target_statuses_for_hostname, que establece los objetivos para todas las entradas con un nombre de host dado a la vez.

1.1.2 (19-Dic-2019)

  • Fix: cuando la API ngx.sleep no está disponible (por ejemplo, en la fase de registro) no es posible bloquear usando lua-resty-lock y cualquier función que necesite acceso exclusivo fallaría. Esta solución añade un método de reintento que inicia un nuevo hilo ligero, que tiene acceso a ngx.sleep, para bloquear la ruta crítica. #37;

1.1.1 (14-Nov-2019)

  • Fix: fallar cuando no es posible obtener acceso exclusivo a la lista de objetivos. Esta solución previene que los trabajadores lleguen a un estado inconsistente. #34;

1.1.0 (30-Sep-2019)

  • Agregar soporte para establecer el encabezado Host personalizado que se utilizará para las verificaciones activas.
  • Fix: registrar error en caso de fallo de SSL Handshake #28;

1.0.0 (05-Jul-2019)

  • BREAKING: todas las funciones de API relacionadas con hosts requieren ahora un argumento hostname. De esta manera, diferentes nombres de host que escuchan en la misma combinación de IP y puertos no se afectan entre sí.
  • Fix: corregir el informe de éxitos de sondas TCP activas #20; corrige el problema #19

0.6.1 (04-Abr-2019)

  • Fix: configurar el callback de eventos solo después de que se cargue la lista de objetivos #18; corrige el problema de Kong #4453

0.6.0 (26-Sep-2018)

  • Introducir el campo checks.active.https_verify_certificate. Es true por defecto; establecerlo en false desactiva la verificación del certificado en las verificaciones de salud activas sobre HTTPS.

0.5.0 (25-Jul-2018)

  • Agregar soporte para https -- gracias @gaetanfl por el PR!
  • Introducir campos separados checks.active.type y checks.passive.type; el campo de nivel superior type todavía se admite como un fallback pero ahora está desaprobado.

0.4.2 (23-May-2018)

  • Fix: encabezado Host en verificaciones de salud activas

0.4.1 (21-May-2018)

  • Fix: gestión interna de contadores de verificación de salud

0.4.0 (20-Mar-2018)

  • Corrección de la configuración de valores predeterminados en http_statuses
  • Comprobación de tipo y límites en la tabla checks

0.3.0 (18-Dic-2017)

  • Desactivar verificaciones individuales estableciendo sus contadores en 0

0.2.0 (30-Nov-2017)

  • Agrega set_target_status

0.1.0 (27-Nov-2017) Lanzamiento inicial

  • Carga inicial

GitHub

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-healthcheck.