Перейти к содержанию

consul: Библиотека для взаимодействия с HTTP API consul из nginx-module-lua

Установка

Если вы еще не настроили подписку на RPM репозиторий, зарегистрируйтесь. После этого вы можете перейти к следующим шагам.

CentOS/RHEL 7 или 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

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-consul v0.4.0, выпущенную 18 августа 2021 года.

Библиотека для взаимодействия с HTTP API consul из ngx_lua

Обзор

Методы возвращают объект ответа lua-resty-http. Тело ответа было прочитано и установлено в res.body, декодировано из JSON, если в заголовке ответа есть Content-Type с значением Application/JSON.

Все заголовки ответа доступны в res.headers.

Параметр ACL Token всегда отправляется как заголовок X-Consul-Token, а не включается в строку запроса.

Если указаны аргументы wait или index, тайм-аут чтения запроса увеличивается соответственно. wait должен быть передан в виде числа секунд, не включайте s или любую другую строку единицы измерения.

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 декодированный ответ

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 декодированный ответ

local res, err = consul:list_keys() -- Получить все ключи
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) -- Значение ключа после декодирования из base64
end

Основные методы

new

syntax: client = consul:new(opts?)

Создает новый клиент consul. opts — это таблица, устанавливающая следующие параметры:

  • host По умолчанию 127.0.0.1
  • port По умолчанию 8500. Установите в 0, если используете unix-сокет в качестве host.
  • connect_timeout Тайм-аут подключения в мс. По умолчанию 60с
  • read_timeout Тайм-аут чтения в мс. По умолчанию 60с
  • default_args Таблица аргументов строки запроса, которые отправляются со всеми запросами (например, token). По умолчанию пустая.
  • ssl Логическое значение, включающее HTTPS-запросы. По умолчанию false.
  • ssl_verify Логическое значение, проверяющее SSL-сертификаты. По умолчанию true.
  • sni_host Имя хоста, используемое при проверке SSL-сертификатов.

get

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

Выполняет GET-запрос к указанному пути. Версия API автоматически добавляется в начало.

args — это таблица параметров строки запроса, которые добавляются к URI.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

put

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

Выполняет PUT-запрос к указанному пути. Версия API автоматически добавляется в начало.

args — это таблица параметров строки запроса, которые добавляются к URI.

Если body является таблицей или логическим значением, он автоматически кодируется в JSON перед отправкой. В противном случае допустимо любое значение, которое lua-resty-http принимает в качестве входных данных тела.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

delete

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

Выполняет GET-запрос к указанному пути. Версия API автоматически добавляется в начало.

args — это таблица параметров строки запроса, которые добавляются к URI.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

get_client_body_reader

Метод-прокси к lua-resty-http

Помощники для ключей и значений

Эти методы автоматически добавляют /v1/kv, только фактический ключ должен быть передан. Значения, закодированные в base64, автоматически декодируются.

get_key

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

Получить ключ KV Consul. Значения декодируются из Base64.

args — это таблица параметров строки запроса, которые добавляются к URI.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

put_key

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

Создать или обновить ключ KV.

args — это таблица параметров строки запроса, которые добавляются к URI.

Если value является таблицей или логическим значением, он автоматически кодируется в JSON перед отправкой. В противном случае допустимо любое значение, которое lua-resty-http принимает в качестве входных данных тела.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

delete

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

Удалить запись KV.

args — это таблица параметров строки запроса, которые добавляются к URI.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

list_keys

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

Получить все ключи в хранилище KV. Опционально в пределах prefix.

args — это таблица параметров строки запроса, которые добавляются к URI. keys всегда устанавливается как параметр строки запроса с этим методом.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

Помощник транзакций

txn

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

Выполняет PUT запрос к API-эндпоинту /v1/txn с предоставленным полезным грузом.

payload может быть предоставлен в виде таблицы Lua, в этом случае ключи Value будут автоматически закодированы в base64. В противном случае допустимо любое значение, которое lua-resty-http принимает в качестве входных данных тела.

Возвращает объект ответа lua-resty-http. В случае ошибки возвращает nil и сообщение об ошибке.

Значения KV в теле ответа автоматически декодируются из 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

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-consul.