healthcheck: Biblioteca de healthcheck para nginx-module-lua para validar o status do serviço upstream

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Em seguida, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou 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 com o NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-healthcheck v3.1.1 lançado em 19 de novembro de 2025.

última versão última versão do luarocks

Uma biblioteca de verificação de saúde para OpenResty.

Sinopse

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, "falha ao configurar eventos do trabalhador: ", 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
                -- um alvo foi removido
                ngx.log(ngx.DEBUG,"Alvo removido: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname == checker.events.healthy
                -- alvo mudou de estado, ou foi adicionado
                ngx.log(ngx.DEBUG,"Alvo mudou para saudável: ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname ==  checker.events.unhealthy
                -- alvo mudou de estado, ou foi adicionado
                ngx.log(ngx.DEBUG,"Alvo mudou para não saudável: ",
                    target.ip, ":", target.port, " ", target.hostname)
            else
                -- evento desconhecido
            end
        end
    }
}

Descrição

Esta biblioteca suporta a realização de verificações de saúde ativas e passivas em hosts arbitrários.

O controle da biblioteca acontece através de sua API programática. O consumo de seus eventos ocorre através da biblioteca lua-resty-worker-events.

Os alvos são adicionados usando checker:add_target(host, port). Mudanças no status ("saudável" ou "não saudável") são transmitidas via eventos de trabalhador.

As verificações ativas são executadas em segundo plano com base nos intervalos de temporizador especificados.

Para verificações de saúde passivas, a biblioteca recebe notificações explícitas através de sua API programática usando funções como checker:report_http_status(host, port, status).

Consulte a documentação online do LDoc para a API completa.

Histórico

A versionação é estritamente baseada em Semantic Versioning

Lançando novas versões:

atualize o changelog abaixo (os PRs devem ser mesclados incluindo uma entrada no changelog)
com base no changelog, determine a nova versão SemVer
crie um novo rockspec
renderize a documentação usando ldoc (não faça isso dentro de PRs)
faça commit como "release x.x.x" (não inclua a revisão do rockspec)
marque o commit com "x.x.x" (não inclua a revisão do rockspec)
envie o commit e a tag
faça upload do rock para luarocks: luarocks upload rockspecs/[name] --api-key=abc

3.1.1 (19-Nov-2025)

Fix: altere os cabeçalhos padrão para uma tabela vazia em vez de um array para remover o aviso de descontinuação #174

3.1.0 (19-Jun-2024)

Feat: remova a verificação de versão do resty.events #162

3.0.2 (16-May-2024)

Fix: evite criar múltiplos temporizadores para executar a mesma verificação ativa #157

3.0.1 (22-Dec-2023)

Fix: corrija a lógica de limpeza de atraso quando múltiplos healthcheckers foram iniciados #146

3.0.0 (12-Oct-2023)

Perf: otimize localizando algumas funções #92 (backport)
Fix: Gere novos http_statuses padrão dentro de new() #83 (backport)

2.0.0 (22-Sep-2020)

Nota: As mudanças nesta versão foram descartadas do desenvolvimento atual e futuro. Abaixo você pode ver seu changelog, mas esteja ciente de que essas mudanças podem não estar presentes em 3.y.z, a menos que sejam explicitamente declaradas em 3.y.z, 1.6.3 ou lançamentos anteriores. Leia mais em: release 3.0.0 (#142) e chore(*): realinhar branch master para o lançamento 3.0.0 (#144)

BREAKING: fallback para o campo de nível superior type descontinuado agora foi removido (descontinuado desde 0.5.0) #56

BREAKING: Aumentar a dependência lua-resty-worker-events para 2.0.0. Isso torna muitas das APIs nesta biblioteca assíncronas, pois os eventos de trabalhador post e post_local não chamarão mais poll em um trabalhador em execução automaticamente, para mais informações, veja: https://github.com/Kong/lua-resty-worker-events#200-16-september-2020

BREAKING: tcp_failures não pode mais ser 0 em verificações http(s) (a menos que http(s)_failures também sejam definidos como 0) #55

feature: Adicionada suporte para https_sni #49

fix: registre corretamente os números das linhas usando chamadas de cauda #29

fix: ao não fornecer um hostname, use IP #48

fix: makefile; make install

feature: adicionado um campo de versão de status #54

feature: adicione cabeçalhos para solicitação de probe #54

fix: saia cedo ao recarregar durante um probe #47

fix: evite que a lista de alvos seja nil, devido ao comportamento assíncrono #44

fix: substitua temporizador e bloqueios em todo o nó por resty-timer, para evitar pulos de intervalo #59

change: adicionei registro adicional ao postar eventos #25

fix: não fique sem temporizadores durante init/init_worker ao adicionar uma grande quantidade de alvos #57

fix: não chame na tabela do módulo, mas use um método para bloqueios. Também em #57

1.6.3 (06-Sep-2023)

Feature: Adicionada suporte para https_sni #49 (backport)
Fix: Use a API do OpenResty para mTLS #99 (backport)

1.6.2 (17-Nov-2022)

Fix: evite levantar eventos de trabalhador para novos alvos que foram marcados para remoção atrasada, ou seja, alvos que já existem na memória só precisam ter a flag de remoção limpa quando adicionados novamente. #122

1.6.1 (25-Jul-2022)

Fix: melhorias para garantir o correto bloqueio de recursos compartilhados para evitar condições de corrida e relatar claramente estados de falha. #112, #113, #114.
Fix: reduza a frequência de verificação de alvos não utilizados, reduzindo o número de bloqueios criados. #116
Aceite qualquer versão lua-resty-events 0.1.x release. #118

1.6.0 (27-Jun-2022)

Feature: introduza suporte ao módulo lua-resty-events além do suporte ao lua-resty-worker-events. Com essa adição, o pacote lua-resty-healthcheck do luarocks não requer mais um módulo de compartilhamento de eventos específico, mas você ainda deve fornecer seja lua-resty-worker-events ou lua-resty-events. #105
Change: se disponível, lua-resty-healthcheck agora usa string.buffer, a nova API de serialização do LuaJIT. Se não estiver disponível, lua-resty-healthcheck volta para cjson. #109

1.5.3 (14-Nov-2022)

Fix: evite levantar eventos de trabalhador para novos alvos que foram marcados para remoção atrasada, ou seja, alvos que já existem na memória só precisam ter a flag de remoção limpa quando adicionados novamente. #121

1.5.2 (07-Jul-2022)

Melhor gerenciamento dos modos de falha do resty.lock, adicionando mais verificações para garantir que o bloqueio seja mantido antes de executar o código crítico, e melhorando a decisão sobre se uma função deve ser tentada novamente após um timeout ao tentar adquirir um bloqueio. #113
Aumentada a quantidade de logs para falhas de funções bloqueadas. #114
A frequência de limpeza de alvos excluídos foi reduzida, cortando o número de bloqueios criados em um curto período. #116

1.5.1 (23-Mar-2022)

Fix: evite quebrar verificações de saúde ativas ao adicionar ou remover alvos. #93

1.5.0 (09-Feb-2022)

Nova opção checks.active.headers suporta uma ou mais listas de valores indexados por nome de cabeçalho. #87
Introduza a função dealyed_clear(), usada para remover endereços após um intervalo de tempo. Esta função pode ser usada quando um endereço está sendo removido, mas pode ser adicionado novamente antes que o intervalo expire, mantendo seu status de saúde. #88

1.4.3 (31-Mar-2022)

Fix: evite quebrar verificações de saúde ativas ao adicionar ou remover alvos. #100

1.4.2 (29-Jun-2021)

Fix: evite que novas verificações ativas sejam agendadas enquanto uma verificação de saúde está em execução. #72
Fix: remova o observador de eventos ao parar uma verificação de saúde ativa. #74; corrige o problema do Kong #7406

1.4.1 (17-Feb-2021)

Fix: certifique-se de que um único trabalhador verificará ativamente os status dos hosts. #67

1.4.0 (07-Jan-2021)

Use um único temporizador para verificar ativamente os alvos de saúde. Isso reduz o número de temporizadores usados pelos verificadores de saúde, pois costumavam usar dois temporizadores por cada alvo. #62

1.3.0 (17-Jun-2020)

Adiciona suporte a mTLS para verificações de saúde ativas. Este recurso pode ser usado adicionando os campos ssl_cert e ssl_key, com certificado e chave, respectivamente, ao criar um novo objeto de verificação de saúde. #41

1.2.0 (13-Feb-2020)

Adiciona set_all_target_statuses_for_hostname, que define os alvos para todas as entradas com um determinado hostname de uma vez.

1.1.2 (19-Dec-2019)

Fix: quando a API ngx.sleep não está disponível (por exemplo, na fase de log), não é possível bloquear usando lua-resty-lock e qualquer função que precise de acesso exclusivo falharia. Esta correção adiciona um método de tentativa que inicia um novo thread leve, que tem acesso a ngx.sleep, para bloquear o caminho crítico. #37;

1.1.1 (14-Nov-2019)

Fix: falhe quando não for possível obter acesso exclusivo à lista de alvos. Esta correção evita que os trabalhadores cheguem a um estado inconsistente. #34;

1.1.0 (30-Sep-2019)

Adicione suporte para definir o cabeçalho Host personalizado a ser usado para verificações ativas.
Fix: registre erro na falha de handshake SSL #28;

1.0.0 (05-Jul-2019)

BREAKING: todas as funções da API relacionadas a hosts agora exigem um argumento hostname. Dessa forma, diferentes hostnames escutando na mesma combinação de IP e portas não afetam uns aos outros.
Fix: corrija o relatório de sucessos de probe TCP ativos #20; corrige o problema #19

0.6.1 (04-Apr-2019)

Fix: configure o callback de evento apenas após a lista de alvos ser carregada #18; corrige o problema do Kong #4453

0.6.0 (26-Sep-2018)

Introduza o campo checks.active.https_verify_certificate. É true por padrão; definir como false desabilita a verificação de certificado em verificações de saúde ativas sobre HTTPS.

0.5.0 (25-Jul-2018)

Adicione suporte para https -- obrigado @gaetanfl pelo PR!
Introduza campos separados checks.active.type e checks.passive.type; o campo de nível superior type ainda é suportado como fallback, mas agora está descontinuado.

0.4.2 (23-May-2018)

Corrija o cabeçalho Host em verificações de saúde ativas

0.4.1 (21-May-2018)

Corrija o gerenciamento interno dos contadores de verificação de saúde

0.4.0 (20-Mar-2018)

Corrija a configuração dos padrões em http_statuses
Verificação de tipo e limites na tabela checks

0.3.0 (18-Dec-2017)

Desative verificações individuais definindo seus contadores como 0

0.2.0 (30-Nov-2017)

Adiciona set_target_status

0.1.0 (27-Nov-2017) Lançamento inicial

Upload inicial

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-healthcheck.