healthcheck: Bibliothèque de vérification de santé pour nginx-module-lua pour valider l'état des services en amont

Installation

Si vous n'avez pas configuré l'abonnement au dépôt RPM, inscrivez-vous. Ensuite, vous pouvez procéder avec les étapes suivantes.

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

Pour utiliser cette bibliothèque Lua avec NGINX, assurez-vous que nginx-module-lua est installé.

Ce document décrit lua-resty-healthcheck v3.1.1 publié le 19 novembre 2025.

latest version latest luarocks version

Une bibliothèque de vérification de santé pour OpenResty.

Synopsis

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, "échec de la configuration des événements de travail : ", 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,"Événement de : ", sourcename)
            if eventname == checker.events.remove
                -- un cible a été supprimée
                ngx.log(ngx.DEBUG,"Cible supprimée : ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname == checker.events.healthy
                -- la cible a changé d'état, ou a été ajoutée
                ngx.log(ngx.DEBUG,"Cible passée à l'état sain : ",
                    target.ip, ":", target.port, " ", target.hostname)
            elseif eventname ==  checker.events.unhealthy
                -- la cible a changé d'état, ou a été ajoutée
                ngx.log(ngx.DEBUG,"Cible passée à l'état non sain : ",
                    target.ip, ":", target.port, " ", target.hostname)
            else
                -- événement inconnu
            end
        end
    }
}

Description

Cette bibliothèque prend en charge l'exécution de vérifications de santé actives et passives sur des hôtes arbitraires.

Le contrôle de la bibliothèque se fait via son API programmatique. La consommation de ses événements se fait via la bibliothèque lua-resty-worker-events.

Les cibles sont ajoutées en utilisant checker:add_target(host, port). Les changements de statut ("sain" ou "non sain") sont diffusés via les événements de travail.

Les vérifications actives sont exécutées en arrière-plan en fonction des intervalles de minuterie spécifiés.

Pour les vérifications de santé passives, la bibliothèque reçoit des notifications explicites via son API programmatique en utilisant des fonctions telles que checker:report_http_status(host, port, status).

Consultez la documentation LDoc en ligne pour l'API complète.

Historique

Le versionnage est strictement basé sur Semantic Versioning

Publication de nouvelles versions :

mettre à jour le changelog ci-dessous (les PR doivent être fusionnées avec une entrée dans le changelog)
en fonction du changelog, déterminer la nouvelle version SemVer
créer un nouveau rockspec
rendre la documentation en utilisant ldoc (ne pas faire cela dans les PR)
valider comme "release x.x.x" (ne pas inclure la révision du rockspec)
taguer le commit avec "x.x.x" (ne pas inclure la révision du rockspec)
pousser le commit et le tag
télécharger le rock sur luarocks : luarocks upload rockspecs/[name] --api-key=abc

3.1.1 (19-Nov-2025)

Fix : changer les en-têtes par défaut en table vide au lieu d'un tableau pour supprimer l'avis de dépréciation #174

3.1.0 (19-Jun-2024)

Feat : supprimer la vérification de version de resty.events #162

3.0.2 (16-May-2024)

Fix : éviter de créer plusieurs minuteries pour exécuter la même vérification active #157

3.0.1 (22-Dec-2023)

Fix : corriger la logique de nettoyage des délais lorsque plusieurs vérificateurs de santé ont été démarrés #146

3.0.0 (12-Oct-2023)

Perf : optimiser en localisant certaines fonctions #92 (backport)
Fix : générer de nouveaux http_statuses par défaut dans new() #83 (backport)

2.0.0 (22-Sep-2020)

Remarque : Les modifications de cette version ont été abandonnées pour le développement actuel et futur. Vous pouvez voir son changelog ci-dessous, mais soyez conscient que ces modifications pourraient ne pas être présentes dans 3.y.z à moins qu'elles ne soient explicitement déclarées dans 3.y.z, 1.6.3 ou les versions précédentes. Lisez-en plus sur : release 3.0.0 (#142) et chore(*): réaligner la branche master sur la version 3.0.0 (#144)

BREAKING : le champ de niveau supérieur type déprécié est maintenant supprimé (déprécié depuis 0.5.0) #56

BREAKING : Augmenter la dépendance lua-resty-worker-events à 2.0.0. Cela rend une grande partie des API de cette bibliothèque asynchrones car les événements de travail post et post_local n'appelleront plus automatiquement poll sur un travailleur en cours d'exécution, pour plus d'informations, voir : https://github.com/Kong/lua-resty-worker-events#200-16-septembre-2020

BREAKING : tcp_failures ne peut plus être 0 sur les vérifications http(s) (à moins que http(s)_failures ne soient également définis sur 0) #55

fonctionnalité : Ajout du support pour https_sni #49

fix : journaliser correctement les numéros de ligne en utilisant des appels de queue #29

fix : lorsqu'aucun nom d'hôte n'est fourni, utiliser l'IP #48

fix : makefile ; make install

fonctionnalité : ajout d'un champ de version d'état #54

fonctionnalité : ajout d'en-têtes pour la requête de sonde #54

fix : quitter tôt lors du rechargement pendant une sonde #47

fix : empêcher la liste des cibles d'être nulle, en raison du comportement asynchrone #44

fix : remplacer la minuterie et les verrous à l'échelle du nœud par resty-timer, pour éviter les sauts d'intervalle #59

changement : ajout d'une journalisation supplémentaire lors de la publication d'événements #25

fix : ne pas manquer de minuteries pendant init/init_worker lors de l'ajout d'un grand nombre de cibles #57

fix : ne pas appeler sur la table de module, mais utiliser une méthode pour les verrous. Aussi dans #57

1.6.3 (06-Sep-2023)

Fonctionnalité : Ajout du support pour https_sni #49 (backport)
Fix : Utiliser l'API OpenResty pour mTLS #99 (backport)

1.6.2 (17-Nov-2022)

Fix : éviter de déclencher des événements de travail pour de nouvelles cibles qui étaient marquées pour une suppression différée, c'est-à-dire que les cibles qui existent déjà en mémoire n'ont besoin que du drapeau de suppression effacé lorsqu'elles sont ajoutées à nouveau. #122

1.6.1 (25-Jul-2022)

Fix : améliorations pour garantir la sécurisation appropriée des ressources partagées afin d'éviter les conditions de concurrence et de signaler clairement les états d'échec. #112, #113, #114.
Fix : réduire la fréquence de vérification des cibles inutilisées, réduisant le nombre de verrous créés. #116
Fix : accepter toute version lua-resty-events 0.1.x release. #118

1.6.0 (27-Jun-2022)

Fonctionnalité : introduire le support du module lua-resty-events en plus du support de lua-resty-worker-events. Avec cet ajout, le package lua-resty-healthcheck de luarocks ne nécessite plus de module de partage d'événements spécifique, mais vous devez toujours fournir soit lua-resty-worker-events soit lua-resty-events. #105
Changement : si disponible, lua-resty-healthcheck utilise désormais string.buffer, la nouvelle API de sérialisation de LuaJIT. S'il n'est pas disponible, lua-resty-healthcheck revient à cjson. #109

1.5.3 (14-Nov-2022)

Fix : éviter de déclencher des événements de travail pour de nouvelles cibles qui étaient marquées pour une suppression différée, c'est-à-dire que les cibles qui existent déjà en mémoire n'ont besoin que du drapeau de suppression effacé lorsqu'elles sont ajoutées à nouveau. #121

1.5.2 (07-Jul-2022)

Meilleure gestion des modes d'échec de resty.lock, ajoutant plus de vérifications pour garantir que le verrou est détenu avant d'exécuter du code critique, et améliorant la décision de savoir si une fonction doit être réessayée après un délai d'attente lors de la tentative d'acquisition d'un verrou. #113
Augmentation de la journalisation des échecs de fonction verrouillée. #114
La fréquence de nettoyage des cibles supprimées a été réduite, réduisant le nombre de verrous créés sur une courte période. #116

1.5.1 (23-Mar-2022)

Fix : éviter de casser les vérifications de santé actives lors de l'ajout ou de la suppression de cibles. #93

1.5.0 (09-Feb-2022)

Nouvelle option checks.active.headers prend en charge une ou plusieurs listes de valeurs indexées par nom d'en-tête. #87
Introduire la fonction dealyed_clear(), utilisée pour supprimer des adresses après un intervalle de temps. Cette fonction peut être utilisée lorsqu'une adresse est en cours de suppression mais peut être ajoutée à nouveau avant l'expiration de l'intervalle, en conservant son statut de santé. #88

1.4.3 (31-Mar-2022)

Fix : éviter de casser les vérifications de santé actives lors de l'ajout ou de la suppression de cibles. #100

1.4.2 (29-Jun-2021)

Fix : empêcher de nouvelles vérifications actives d'être programmées pendant qu'une vérification de santé est en cours. #72
Fix : supprimer le moniteur d'événements lors de l'arrêt d'une vérification de santé active. #74 ; corrige le problème Kong #7406

1.4.1 (17-Feb-2021)

Fix : s'assurer qu'un seul travailleur vérifiera activement les statuts des hôtes. #67

1.4.0 (07-Jan-2021)

Utiliser une seule minuterie pour vérifier activement les cibles. Cela réduit le nombre de minuteries utilisées par les vérificateurs de santé, car ils utilisaient auparavant deux minuteries par cible. #62

1.3.0 (17-Jun-2020)

Ajoute le support pour mTLS aux vérifications de santé actives. Cette fonctionnalité peut être utilisée en ajoutant les champs ssl_cert et ssl_key, avec le certificat et la clé respectivement, lors de la création d'un nouvel objet de vérification de santé. #41

1.2.0 (13-Feb-2020)

Ajoute set_all_target_statuses_for_hostname, qui définit les cibles pour toutes les entrées avec un nom d'hôte donné en une seule fois.

1.1.2 (19-Dec-2019)

Fix : lorsque l'API ngx.sleep n'est pas disponible (par exemple, dans la phase de journalisation), il n'est pas possible de verrouiller en utilisant lua-resty-lock et toute fonction nécessitant un accès exclusif échouerait. Cette correction ajoute une méthode de réessai qui démarre un nouveau thread léger, qui a accès à ngx.sleep, pour verrouiller le chemin critique. #37;

1.1.1 (14-Nov-2019)

Fix : échouer lorsqu'il n'est pas possible d'obtenir un accès exclusif à la liste des cibles. Cette correction empêche les travailleurs d'atteindre un état incohérent. #34;

1.1.0 (30-Sep-2019)

Ajouter le support pour définir l'en-tête Host personnalisé à utiliser pour les vérifications actives.
Fix : journaliser l'erreur en cas d'échec de la poignée SSL #28;

1.0.0 (05-Jul-2019)

BREAKING : toutes les fonctions API liées aux hôtes nécessitent maintenant un argument hostname. De cette manière, différents noms d'hôtes écoutant la même combinaison d'IP et de ports n'ont pas d'effet les uns sur les autres.
Fix : corriger le rapport des succès de sonde TCP actifs #20; corrige le problème #19

0.6.1 (04-Apr-2019)

Fix : configurer le rappel d'événement uniquement après le chargement de la liste des cibles #18; corrige le problème Kong #4453

0.6.0 (26-Sep-2018)

Introduire le champ checks.active.https_verify_certificate. Il est true par défaut ; le définir sur false désactive la vérification du certificat dans les vérifications de santé actives via HTTPS.

0.5.0 (25-Jul-2018)

Ajouter le support pour https -- merci @gaetanfl pour la PR !
Introduire des champs séparés checks.active.type et checks.passive.type ; le champ type de niveau supérieur est toujours pris en charge comme solution de secours mais est maintenant déprécié.

0.4.2 (23-May-2018)

Fix : en-tête Host dans les vérifications de santé actives

0.4.1 (21-May-2018)

Fix : gestion interne des compteurs de vérification de santé

0.4.0 (20-Mar-2018)

Correction de la définition des valeurs par défaut dans http_statuses
Vérification de type et de limites pour la table checks

0.3.0 (18-Dec-2017)

Désactiver des vérifications individuelles en définissant leurs compteurs à 0

0.2.0 (30-Nov-2017)

Ajoute set_target_status

0.1.0 (27-Nov-2017) Première version

Téléchargement initial

GitHub

Vous pouvez trouver des conseils de configuration supplémentaires et de la documentation pour ce module dans le dépôt GitHub pour nginx-module-healthcheck.