Saltar a contenido

consul: Biblioteca para interactuar con la API HTTP de consul desde nginx-module-lua

Instalación

Si no has configurado la suscripción al repositorio RPM, regístrate. Luego puedes proceder con los siguientes pasos.

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

Para utilizar esta biblioteca Lua con NGINX, asegúrate de que nginx-module-lua esté instalado.

Este documento describe lua-resty-consul v0.4.0 lanzado el 18 de agosto de 2021.

Biblioteca para interactuar con la API HTTP de consul desde ngx_lua

Descripción general

Los métodos devuelven un objeto de respuesta de lua-resty-http.
El cuerpo de la respuesta se ha leído y se ha establecido en res.body, decodificado en JSON si la respuesta tiene un encabezado Content-Type de Application/JSON.

Todos los encabezados de respuesta están disponibles en res.headers.

El parámetro de token ACL siempre se envía como el encabezado X-Consul-Token en lugar de incluirse en la cadena de consulta.

Si se proporcionan los argumentos wait o index, el tiempo de espera de lectura de la solicitud se extiende adecuadamente.
wait debe pasarse como un número de segundos, no incluyas s ni ninguna otra cadena de unidad.

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 -- Respuesta decodificada 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 -- Respuesta decodificada en JSON

local res, err = consul:list_keys() -- Obtener todas las claves
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) -- Valor de la clave después de la decodificación base64
end

Métodos básicos

new

syntax: client = consul:new(opts?)

Crea un nuevo cliente de consul. opts es una tabla que establece las siguientes opciones:

  • host Por defecto es 127.0.0.1
  • port Por defecto es 8500. Establecer en 0 si se utiliza un socket unix como host.
  • connect_timeout Tiempo de espera de conexión en ms. Por defecto es 60s
  • read_timeout Tiempo de espera de lectura en ms. Por defecto es 60s
  • default_args Tabla de argumentos de cadena de consulta para enviar con todas las solicitudes (por ejemplo, token). Por defecto está vacía.
  • ssl Booleano, habilitar solicitudes HTTPS. Por defecto es false.
  • ssl_verify Booleano, verificar certificados SSL. Por defecto es true.
  • sni_host Nombre de host a utilizar al verificar certificados SSL.

get

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

Realiza una solicitud GET a la ruta proporcionada. La versión de la API se antepone automáticamente.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

put

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

Realiza una solicitud PUT a la ruta proporcionada. La versión de la API se antepone automáticamente.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Si body es una tabla o un valor booleano, se codifica automáticamente en JSON antes de ser enviado.
De lo contrario, cualquier cosa que lua-resty-http acepte como entrada de cuerpo es válida.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

delete

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

Realiza una solicitud GET a la ruta proporcionada. La versión de la API se antepone automáticamente.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

get_client_body_reader

Método proxy a lua-resty-http

Ayudantes de clave-valor

Estos métodos anteponen automáticamente /v1/kv, solo se debe pasar la clave real.
Los valores codificados en base64 se decodifican automáticamente.

get_key

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

Recupera una clave KV de Consul. Los valores se decodifican en Base64.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

put_key

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

Crea o actualiza una clave KV.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Si value es una tabla o un valor booleano, se codifica automáticamente en JSON antes de ser enviado.
De lo contrario, cualquier cosa que lua-resty-http acepte como entrada de cuerpo es válida.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

delete

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

Elimina una entrada KV.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

list_keys

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

Recupera todas las claves en el almacén KV. Opcionalmente dentro de un prefix.

args es una tabla de parámetros de cadena de consulta para agregar a la URI.
keys siempre se establece como un parámetro de cadena de consulta con este método.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

Ayudante de transacciones

txn

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

Realiza una solicitud PUT al punto final de la API /v1/txn con la carga útil proporcionada.

payload puede proporcionarse como una tabla Lua, en cuyo caso las claves Value se codificarán automáticamente en base64.
De lo contrario, cualquier cosa que lua-resty-http acepte como entrada de cuerpo es válida.

Devuelve un objeto de respuesta de lua-resty-http.
En caso de error, devuelve nil y un mensaje de error.

Los valores KV en el cuerpo de la respuesta se decodifican automáticamente 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

Puedes encontrar consejos de configuración adicionales y documentación para este módulo en el repositorio de GitHub para nginx-module-consul.