Saltar a contenido

healthcheck: Biblioteca de verificación de estado 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.1 lanzado el 19 de noviembre de 2025.

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

Una biblioteca de verificación de estado 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 estado 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 utilizando 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 estado 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

Lanzamiento de nuevas versiones:

  • actualizar el changelog a continuación (los PR deben fusionarse 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 los PR)
  • confirmar como "release x.x.x" (no incluir la revisión del rockspec)
  • etiquetar la confirmación con "x.x.x" (no incluir la revisión del rockspec)
  • empujar la confirmación y la etiqueta
  • subir el rock a luarocks: luarocks upload rockspecs/[name] --api-key=abc

3.1.1 (19-Nov-2025)

  • Fix: cambiar los encabezados predeterminados a una tabla vacía en lugar de un array para eliminar el aviso de deprecació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-Dec-2023)

  • Fix: corregir la lógica de limpieza de retraso cuando se iniciaron múltiples healthcheckers #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 lanzamientos anteriores. Lee más en: release 3.0.0 (#142) y chore(*): realign master branch to 3.0.0 release (#144)

  • BREAKING: el fallback para el campo de nivel superior type obsoleto ahora se ha eliminado (obsoleto 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 de trabajador post y post_local ya no llamarán automáticamente a poll en un trabajador en ejecución, para más información, ver: 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: Se agregó 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 hostname, usar IP #48
  • fix: makefile; make install
  • feature: se agregó 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: Se agregó 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 versió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 utiliza 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 de 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, cortando 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-Jan-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 se puede utilizar 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 estados de los objetivos para todas las entradas con un hostname dado a la vez.

1.1.2 (19-Dec-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 fallo de SSL Handshake #28;

1.0.0 (05-Jul-2019)

  • BREAKING: todas las funciones de la 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 afectan entre sí.
  • Fix: corregir el reporte de éxitos de sondeos TCP activos #20; corrige el problema #19

0.6.1 (04-Apr-2019)

  • Fix: configurar el callback de evento solo después de que la lista de objetivos esté cargada #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 a través de 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 aún se admite como un fallback pero ahora está obsoleto.

0.4.2 (23-May-2018)

  • Fix: encabezado Host en las 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-Dec-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.