Zum Inhalt

consul: Bibliothek zur Schnittstelle mit der Consul HTTP API von nginx-module-lua

Installation

Wenn Sie das RPM-Repository-Abonnement noch nicht eingerichtet haben, melden Sie sich an. Dann können Sie mit den folgenden Schritten fortfahren.

CentOS/RHEL 7 oder 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

Um diese Lua-Bibliothek mit NGINX zu verwenden, stellen Sie sicher, dass nginx-module-lua installiert ist.

Dieses Dokument beschreibt lua-resty-consul v0.4.0, veröffentlicht am 18. August 2021.

Bibliothek zur Schnittstelle mit der Consul HTTP API von ngx_lua

Übersicht

Methoden geben alle ein lua-resty-http Antwortobjekt zurück.
Der Antwortkörper wurde gelesen und in res.body gesetzt, JSON dekodiert, wenn die Antwort einen Content-Type Header von Application/JSON hat.

Alle Antwortheader sind unter res.headers verfügbar.

Der ACL-Token-Parameter wird immer als X-Consul-Token Header gesendet, anstatt in der Abfragezeichenfolge enthalten zu sein.

Wenn wait oder index Argumente bereitgestellt werden, wird der Lese-Timeout der Anfrage entsprechend verlängert.
wait muss als Anzahl von Sekunden übergeben werden, schließen Sie s oder eine andere Einheit nicht ein.

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 -- JSON dekodierte Antwort

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 -- JSON dekodierte Antwort

local res, err = consul:list_keys() -- Alle Schlüssel abrufen
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) -- Schlüsselwert nach Base64-Dekodierung
end

Grundlegende Methoden

new

syntax: client = consul:new(opts?)

Erstellt einen neuen Consul-Client. opts ist eine Tabelle, die die folgenden Optionen festlegt:

  • host Standardmäßig auf 127.0.0.1
  • port Standardmäßig auf 8500. Setzen Sie auf 0, wenn Sie einen Unix-Socket als host verwenden.
  • connect_timeout Verbindungs-Timeout in ms. Standardmäßig auf 60s
  • read_timeout Lese-Timeout in ms. Standardmäßig auf 60s
  • default_args Tabelle von Abfragezeichenfolgenargumenten, die mit allen Anfragen gesendet werden (z.B. token). Standardmäßig leer
  • ssl Boolean, HTTPS-Anfragen aktivieren. Standardmäßig false.
  • ssl_verify Boolean, SSL-Zertifikate überprüfen. Standardmäßig true.
  • sni_host Hostname, der bei der Überprüfung von SSL-Zertifikaten verwendet werden soll.

get

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

Führt eine GET-Anfrage an den angegebenen Pfad durch. Die API-Version wird automatisch vorangestellt.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

put

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

Führt eine PUT-Anfrage an den angegebenen Pfad durch. Die API-Version wird automatisch vorangestellt.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Wenn body eine Tabelle oder ein boolescher Wert ist, wird sie automatisch JSON-kodiert, bevor sie gesendet wird.
Andernfalls ist alles, was lua-resty-http als Body-Eingabe akzeptiert, gültig.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

delete

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

Führt eine GET-Anfrage an den angegebenen Pfad durch. Die API-Version wird automatisch vorangestellt.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

get_client_body_reader

Proxy-Methode zu lua-resty-http

Schlüsselwert-Hilfsfunktionen

Diese Methoden fügen automatisch /v1/kv hinzu, nur der tatsächliche Schlüssel sollte übergeben werden.
Base64-kodierte Werte werden automatisch dekodiert.

get_key

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

Ruft einen Consul KV-Schlüssel ab. Werte werden Base64-dekodiert.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

put_key

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

Erstellt oder aktualisiert einen KV-Schlüssel.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Wenn value eine Tabelle oder ein boolescher Wert ist, wird sie automatisch JSON-kodiert, bevor sie gesendet wird.
Andernfalls ist alles, was lua-resty-http als Body-Eingabe akzeptiert, gültig.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

delete

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

Löscht einen KV-Eintrag.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

list_keys

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

Ruft alle Schlüssel im KV-Speicher ab. Optional innerhalb eines prefix.

args ist eine Tabelle von Abfragezeichenfolgenparametern, die zur URI hinzugefügt werden sollen.
keys wird immer als Abfragezeichenfolgenparameter mit dieser Methode gesetzt.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

Transaktionshilfe

txn

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

Führt eine PUT-Anfrage an den /v1/txn API-Endpunkt mit dem bereitgestellten Payload durch.

payload kann als Lua-Tabelle bereitgestellt werden, in diesem Fall werden die Value-Schlüssel automatisch base64-kodiert.
Andernfalls ist alles, was lua-resty-http als Body-Eingabe akzeptiert, gültig.

Gibt ein lua-resty-http Antwortobjekt zurück.
Bei einem Fehler gibt es nil und eine Fehlermeldung zurück.

KV-Werte im Antwortkörper werden automatisch base64-dekodiert.

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

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-consul.