lua-upstream: API Lua pour le contrôle des upstreams NGINX

Installation

Vous pouvez installer ce module sur n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

• RedHat Enterprise Linux 7, 8, 9 et 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 et Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-lua-upstream

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 nginx-module-lua-upstream

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_http_lua_upstream_module.so;

Ce document décrit nginx-module-lua-upstream v0.7 publié le 15 mai 2017.

---

http {
    upstream foo.com {
        server 127.0.0.1 fail_timeout=53 weight=4 max_fails=100;
        server agentzh.org:81;
    }

    upstream bar {
        server 127.0.0.2;
    }

    server {
        listen 8080;

        # sortie d'exemple pour l'interface /upstream suivante :
        # upstream foo.com:
        #     addr = 127.0.0.1:80, weight = 4, fail_timeout = 53, max_fails = 100
        #     addr = 106.184.1.99:81, weight = 1, fail_timeout = 10, max_fails = 1
        # upstream bar:
        #     addr = 127.0.0.2:80, weight = 1, fail_timeout = 10, max_fails = 1

        location = /upstreams {
            default_type text/plain;
            content_by_lua_block {
                local concat = table.concat
                local upstream = require "ngx.upstream"
                local get_servers = upstream.get_servers
                local get_upstreams = upstream.get_upstreams

                local us = get_upstreams()
                for _, u in ipairs(us) do
                    ngx.say("upstream ", u, ":")
                    local srvs, err = get_servers(u)
                    if not srvs then
                        ngx.say("échec de l'obtention des serveurs dans l'upstream ", u)
                    else
                        for _, srv in ipairs(srvs) do
                            local first = true
                            for k, v in pairs(srv) do
                                if first then
                                    first = false
                                    ngx.print("    ")
                                else
                                    ngx.print(", ")
                                end
                                if type(v) == "table" then
                                    ngx.print(k, " = {", concat(v, ", "), "}")
                                else
                                    ngx.print(k, " = ", v)
                                end
                            end
                            ngx.print("\n")
                        end
                    end
                end
            }
        }
    }
}

Fonctions

get_upstreams

syntax: names = upstream.get_upstreams()

Obtenez une liste des noms de tous les groupes d'upstream nommés (c'est-à-dire, les blocs upstream {} explicites).

Notez que les groupes d'upstream implicites créés par proxy_pass et autres sont exclus.

get_servers

syntax: servers = upstream.get_servers(upstream_name)

Obtenez les configurations pour tous les serveurs dans le groupe d'upstream spécifié. Veuillez noter qu'un serveur peut avoir plusieurs adresses lorsque son nom de serveur peut être résolu en plusieurs adresses.

La valeur de retour est une table Lua de type tableau. Chaque entrée de la table est une table Lua de type hash qui prend les clés suivantes :

• addr

  adresse(s) socket. peut être soit une chaîne Lua, soit une table Lua de type tableau de chaînes Lua. * backup * fail_timeout * max_fails * name * weight

get_primary_peers

syntax: peers = upstream.get_primary_peers(upstream_name)

Obtenez les configurations pour tous les pairs principaux (non de secours) dans le groupe d'upstream spécifié.

La valeur de retour est une table Lua de type tableau pour tous les pairs principaux. Chaque entrée de la table est une table Lua de type hash (imbriquée) qui prend les clés suivantes :

• current_weight
• effective_weight
• fail_timeout
• fails

• id

  Identifiant (ID) pour le pair. Cet ID peut être utilisé pour référencer un pair dans un groupe dans l'API de modification des pairs. * max_fails * name

  Adresse socket pour le pair actuel * weight * accessed

  Horodatage pour le dernier accès (en secondes depuis l'Époque) * checked

  Horodatage pour la dernière vérification (en secondes depuis l'Époque) * down

  Tient vrai si le pair a été marqué comme "down", sinon cette clé n'est pas présente * conns

  Nombre de connexions actives au pair (cela nécessite NGINX 1.9.0 ou supérieur).

get_backup_peers

syntax: peers = upstream.get_backup_peers(upstream_name)

Obtenez les configurations pour tous les pairs de secours dans le groupe d'upstream spécifié.

La valeur de retour a la même structure que la fonction get_primary_peers.

set_peer_down

syntax: ok, err = upstream.set_peer_down(upstream_name, is_backup, peer_id, down_value)

Définissez l'attribut "down" (booléen) du pair spécifié.

Pour spécifier de manière unique un pair, vous devez indiquer le nom de l'upstream, s'il s'agit ou non d'un pair de secours, et l'ID du pair (commençant à 0).

Notez que cette méthode ne change que les paramètres du pair dans le processus de travail Nginx actuel. Vous devez synchroniser les changements entre tous les travailleurs Nginx vous-même si vous souhaitez un changement à l'échelle du serveur (par exemple, par le biais de ngx_lua's ngx.shared.DICT).

Voici un exemple. Considérons que nous avons un bloc d'upstream "bar" dans nginx.conf :

upstream bar {
    server 127.0.0.2;
    server 127.0.0.3 backup;
    server 127.0.0.4 fail_timeout=23 weight=7 max_fails=200 backup;
}

alors

upstream.set_peer_down("bar", false, 0, true)

éteindra le pair principal correspondant à server 127.0.0.2.

De même,

upstream.set_peer_down("bar", true, 1, true)

éteindra le pair de secours correspondant à server 127.0.0.4 ....

Vous pouvez rallumer un pair en fournissant une valeur false comme 4ème argument.

current_upstream_name

syntax: name = upstream.current_upstream_name()

Renvoie le nom de l'upstream proxifié pour la requête actuelle. S'il n'y a pas d'upstream pour cette requête (pas d'appel proxy_pass), ou si cette fonction est appelée dans une phase antérieure à la phase de contenu, alors la valeur de retour sera nil. Si un port est explicitement inclus dans la définition de l'upstream ou la directive proxy_pass, il sera inclus dans la valeur de retour de cette fonction.

Exemple :

-- upstream my_upstream { ... }
-- proxy_pass http://my_upstream;
upstream.current_upstream_name() --> my_upstream

-- proxy_pass http://example.com:1234;
upstream.current_upstream_name() --> example.com:1234

Notez que les upstreams implicites créés par proxy_pass sont inclus, contrairement à la sortie de upstream.get_upstreams().

supposant que votre luajit est installé dans /opt/luajit :

export LUAJIT_LIB=/opt/luajit/lib

supposant que vous utilisez LuaJIT v2.1 :

export LUAJIT_INC=/opt/luajit/include/luajit-2.1

Ici, nous supposons que vous installeriez votre nginx sous /opt/nginx/.

./configure --prefix=/opt/nginx \ --with-ld-opt="-Wl,-rpath,$LUAJIT_LIB" \ --add-module=/path/to/lua-nginx-module \ --add-module=/path/to/lua-upstream-nginx-module

make -j2 make install

À partir de NGINX 1.9.11, vous pouvez également compiler ce module en tant que module dynamique, en utilisant l'option `--add-dynamic-module=PATH` au lieu de `--add-module=PATH` sur la
ligne de commande `./configure` ci-dessus. Et ensuite, vous pouvez charger explicitement le module dans votre `nginx.conf` via la directive [load_module](http://nginx.org/en/docs/ngx_core_module.html#load_module), par exemple,

```nginx
load_module /path/to/modules/ngx_http_lua_upstream_module.so;

Voir Aussi

• le module ngx_lua : http://github.com/openresty/lua-nginx-module#readme
• la bibliothèque lua-resty-upstream-healthcheck qui utilise l'API Lua fournie par ce module.

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-lua-upstream.