Aller au contenu

consul: Bibliothèque pour interagir avec l'API HTTP consul depuis nginx-module-lua

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-consul

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-consul

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

Ce document décrit lua-resty-consul v0.4.0 publié le 18 août 2021.

Bibliothèque pour interagir avec l'API HTTP consul depuis ngx_lua

Aperçu

Les méthodes retournent toutes un objet de réponse lua-resty-http.
Le corps de la réponse a été lu et est défini sur res.body, décodé en JSON si la réponse a un en-tête Content-Type de Application/JSON.

Tous les en-têtes de réponse sont disponibles à res.headers.

Le paramètre ACL Token est toujours envoyé en tant qu'en-tête X-Consul-Token plutôt que d'être inclus dans la chaîne de requête.

Si les arguments wait ou index sont fournis, le délai d'attente de lecture de la requête est prolongé en conséquence.
wait doit être passé en tant que nombre de secondes, n'incluez pas s ou toute autre chaîne d'unité.

local resty_consul = require('resty.consul')
local consul = resty_consul:new({
        host            = "127.0.0.1",
        port            = 8500,
        connect_timeout = (60*1000), -- 60s
        read_timeout    = (60*1000), -- 60s
        default_args    = {
            token = "my-default-token"
        },
        ssl             = false,
        ssl_verify      = true,
        sni_host        = nil,
    })

local res, err = consul:get('/agent/services')
if not res then
    ngx.log(ngx.ERR, err)
    return
end

ngx.print(res.status) -- 200
local services = res.body -- réponse décodée en JSON

local res, err = consul:put('/agent/service/register', my_service_definition, { token = "override-token" })
if not res then
    ngx.log(ngx.ERR, err)
    return
end

ngx.print(res.status) -- 200
ngx.print(res.headers["X-Consul-Knownleader"]) -- "true"
local service_register_response = res.body -- réponse décodée en JSON

local res, err = consul:list_keys() -- Obtenir toutes les clés
if not res then
    ngx.log(ngx.ERR, err)
    return
end

local keys = {}
if res.status == 200 then
    keys = res.body
end

for _, key in ipairs(keys) do
    local res, err = consul:get_key(key)
    if not res then
        ngx.log(ngx.ERR, err)
        return
    end

    ngx.print(res.body[1].Value) -- Valeur de la clé après décodage base64
end

Méthodes de base

new

syntax: client = consul:new(opts?)

Crée un nouveau client consul. opts est une table définissant les options suivantes :

  • host Par défaut 127.0.0.1
  • port Par défaut 8500. À définir sur 0 si vous utilisez un socket unix comme host.
  • connect_timeout Délai d'attente de connexion en ms. Par défaut 60s
  • read_timeout Délai d'attente de lecture en ms. Par défaut 60s
  • default_args Table des arguments de chaîne de requête à envoyer avec toutes les requêtes (par exemple, token) Par défaut vide
  • ssl Booléen, activer les requêtes HTTPS. Par défaut false.
  • ssl_verify Booléen, vérifier les certificats SSL. Par défaut true.
  • sni_host Nom d'hôte à utiliser lors de la vérification des certificats SSL.

get

syntax: res, err = consul:get(path, args?)

Effectue une requête GET vers le chemin fourni. La version de l'API est automatiquement préfixée.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

put

syntax: res, err = consul:put(path, body, args?)

Effectue une requête PUT vers le chemin fourni. La version de l'API est automatiquement préfixée.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Si body est une table ou une valeur booléenne, elle est automatiquement encodée en JSON avant d'être envoyée.
Sinon, tout ce que lua-resty-http accepte comme entrée de corps est valide.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

delete

syntax: res, err = consul:delete(path, args?)

Effectue une requête GET vers le chemin fourni. La version de l'API est automatiquement préfixée.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

get_client_body_reader

Méthode proxy pour lua-resty-http

Helpers de clé-valeur

Ces méthodes préfixent automatiquement /v1/kv, seule la clé réelle doit être passée.
Les valeurs encodées en base64 sont automatiquement décodées.

get_key

syntax: res, err = consul:get_key(key, args?)

Récupère une clé KV de Consul. Les valeurs sont décodées en Base64.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

put_key

syntax: res, err = consul:put_key(key, value, args?)

Crée ou met à jour une clé KV.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Si value est une table ou une valeur booléenne, elle est automatiquement encodée en JSON avant d'être envoyée.
Sinon, tout ce que lua-resty-http accepte comme entrée de corps est valide.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

delete

syntax: res, err = consul:delete_key(key, args?)

Supprime une entrée KV.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

list_keys

syntax: res, err = consul:list_keys(prefix?, args?)

Récupère toutes les clés dans le magasin KV. Optionnellement dans un prefix.

args est une table de paramètres de chaîne de requête à ajouter à l'URI.
keys est toujours défini comme un paramètre de chaîne de requête avec cette méthode.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

Helper de transaction

txn

syntax: res, err = consul:txn(payload, args?)

Effectue une requête PUT vers le point de terminaison API /v1/txn avec le payload fourni.

payload peut être fourni sous forme de table Lua, auquel cas les clés Value seront automatiquement encodées en base64.
Sinon, tout ce que lua-resty-http accepte comme entrée de corps est valide.

Retourne un objet de réponse lua-resty-http.
En cas d'erreur, retourne nil et un message d'erreur.

Les valeurs KV dans le corps de la réponse sont automatiquement décodées en base64.

local txn_payload = {
    {
        KV = {
            Verb   = "set",
            Key    = "foo",
            Value  = "bar",
        }
    },
    {
        KV = {
            Verb   = "get",
            Key    = "foobar",
        }
    }
}

local consul = resty_consul:new()

local res, err = consul:txn(txn_payload)
if not res then
    ngx.say(err)
    return
end

ngx.say(res.body.Results[2].KV.Value) -- "bar"

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