Pular para conteúdo

consul: Biblioteca para interface com a API HTTP do consul a partir do nginx-module-lua

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Em seguida, você pode prosseguir com os seguintes passos.

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

Para usar esta biblioteca Lua com o NGINX, certifique-se de que o nginx-module-lua está instalado.

Este documento descreve lua-resty-consul v0.4.0 lançado em 18 de agosto de 2021.

Biblioteca para interface com a API HTTP do consul a partir do ngx_lua

Visão Geral

Os métodos retornam todos um objeto de resposta lua-resty-http.
O corpo da resposta foi lido e definido como res.body, decodificado em JSON se a resposta tiver um cabeçalho Content-Type de Application/JSON.

Todos os cabeçalhos de resposta estão disponíveis em res.headers.

O parâmetro Token ACL é sempre enviado como o cabeçalho X-Consul-Token em vez de ser incluído na string de consulta.

Se os argumentos wait ou index forem fornecidos, o tempo limite de leitura da solicitação é estendido adequadamente.
wait deve ser passado como um número de segundos, não inclua s ou qualquer outra string de unidade.

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 -- Resposta decodificada em 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 -- Resposta decodificada em JSON

local res, err = consul:list_keys() -- Obter todas as chaves
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 da chave após a decodificação base64
end

Métodos Básicos

new

syntax: client = consul:new(opts?)

Cria um novo cliente consul. opts é uma tabela que define as seguintes opções:

  • host Padrão para 127.0.0.1
  • port Padrão para 8500. Defina como 0 se usar um socket unix como host.
  • connect_timeout Tempo limite de conexão em ms. Padrão para 60s
  • read_timeout Tempo limite de leitura em ms. Padrão para 60s
  • default_args Tabela de argumentos da string de consulta a serem enviados com todas as solicitações (por exemplo, token). Padrão para vazio
  • ssl Booleano, habilita solicitações HTTPS. Padrão para false.
  • ssl_verify Booleano, verifica certificados SSL. Padrão para true.
  • sni_host Nome do host a ser usado ao verificar certificados SSL.

get

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

Realiza uma solicitação GET para o caminho fornecido. A versão da API é automaticamente precedida.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

put

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

Realiza uma solicitação PUT para o caminho fornecido. A versão da API é automaticamente precedida.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Se body for uma tabela ou valor booleano, ele é automaticamente codificado em JSON antes de ser enviado.
Caso contrário, qualquer coisa que lua-resty-http aceite como entrada de corpo é válida.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

delete

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

Realiza uma solicitação GET para o caminho fornecido. A versão da API é automaticamente precedida.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

get_client_body_reader

Método proxy para lua-resty-http

Auxiliares de Chave-Valor

Esses métodos automaticamente precedem /v1/kv, apenas a chave real deve ser passada.
Valores codificados em Base64 são automaticamente decodificados.

get_key

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

Recupera uma chave KV do Consul. Os valores são decodificados em Base64.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

put_key

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

Cria ou atualiza uma chave KV.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Se value for uma tabela ou valor booleano, ele é automaticamente codificado em JSON antes de ser enviado.
Caso contrário, qualquer coisa que lua-resty-http aceite como entrada de corpo é válida.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

delete

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

Deleta uma entrada KV.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

list_keys

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

Recupera todas as chaves no armazenamento KV. Opcionalmente dentro de um prefix.

args é uma tabela de parâmetros da string de consulta a serem adicionados à URI.
keys é sempre definido como um parâmetro da string de consulta com este método.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

Auxiliar de Transação

txn

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

Realiza uma solicitação PUT para o endpoint da API /v1/txn com o payload fornecido.

payload pode ser fornecido como uma tabela Lua, caso em que as chaves Value serão automaticamente codificadas em base64.
Caso contrário, qualquer coisa que lua-resty-http aceite como entrada de corpo é válida.

Retorna um objeto de resposta lua-resty-http.
Em caso de erro, retorna nil e uma mensagem de erro.

Os valores KV no corpo da resposta são automaticamente decodificados em 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

Você pode encontrar dicas de configuração adicionais e documentação para este módulo no repositório GitHub do nginx-module-consul.