healthcheck: Biblioteca de verificação de saúde 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.2 lançado em 09 de abril de 2026.

latest version latest luarocks version

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 de 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).

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

Histórico

A versionamento é estritamente baseado em Versionamento Semântico

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.2 (09-Abr-2026)

Fix(active-checks): use HTTP/1.1 para sondas de verificação de saúde com negociação automática de versão #176

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-Mai-2024)

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

3.0.1 (22-Dez-2023)

Fix: conserte a lógica de limpeza de atraso quando múltiplos verificadores de saúde foram iniciados #146

3.0.0 (12-Out-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-Set-2020)

Nota: 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 do 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 retorno #29

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

fix: makefile; make install

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

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

fix: saia cedo ao recarregar durante uma sondagem #47

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

fix: substitua temporizador e bloqueios de nó por resty-timer, para evitar saltos de intervalo #59

change: adicione logging adicional na postagem de 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-Set-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 precisam apenas da flag de remoção limpa quando adicionados novamente. #122

1.6.1 (25-Jul-2022)

Fix: melhorias para garantir a segurança adequada 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
Fix: aceite qualquer versão lua-resty-events 0.1.x. #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 é obrigado a fornecer ou 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 recua 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 precisam apenas da 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 código crítico, e melhorando a decisão sobre se uma função deve ser tentada novamente após um tempo limite ao tentar adquirir um bloqueio. #113
Aumentada a gravação 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 pelo nome do 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 a questão 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 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 o certificado e a 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 só vez.

1.1.2 (19-Dez-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 nova 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: falhar 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-Set-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 requerem um argumento hostname. Dessa forma, diferentes hostnames ouvindo na mesma combinação de IP e portas não têm efeito uns sobre os outros.
Fix: conserte o relatório de sucessos de sondagem TCP ativa #20; corrige a questão #19

0.6.1 (04-Abr-2019)

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

0.6.0 (26-Set-2018)

Introduza o campo checks.active.https_verify_certificate. É true por padrão; defini-lo como false desabilita a verificação de certificado em verificações de saúde ativas via 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 um fallback, mas agora está descontinuado.

0.4.2 (23-Mai-2018)

Fix: cabeçalho Host em verificações de saúde ativas

0.4.1 (21-Mai-2018)

Fix: gerenciamento interno dos contadores de verificação de saúde

0.4.0 (20-Mar-2018)

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

0.3.0 (18-Dez-2017)

Desabilite 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.