跳转至

consul: 用于从 nginx-module-lua 接口与 consul HTTP API 的库

安装

如果您尚未设置 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

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-consul v0.4.0，于 2021 年 8 月 18 日发布。

用于从 ngx_lua 接口与 consul HTTP API 的库

概述

所有方法都返回一个 lua-resty-http 响应对象。 响应体已被读取并设置为 res.body，如果响应的 Content-Type 头为 Application/JSON，则进行 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

语法: client = consul:new(opts?)

创建一个新的 consul 客户端。opts 是一个设置以下选项的表：

  • host 默认为 127.0.0.1
  • port 默认为 8500。如果使用 unix 套接字作为 host，则设置为 0。
  • connect_timeout 连接超时（毫秒）。默认为 60s
  • read_timeout 读取超时（毫秒）。默认为 60s
  • default_args 要与所有请求一起发送的查询字符串参数表（例如 token），默认为空
  • ssl 布尔值，启用 HTTPS 请求。默认为 false。
  • ssl_verify 布尔值，验证 SSL 证书。默认为 true。
  • sni_host 验证 SSL 证书时使用的主机名。

get

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

对提供的路径执行 GET 请求。API 版本会自动添加前缀。

args 是一个要添加到 URI 的查询字符串参数表。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

put

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

对提供的路径执行 PUT 请求。API 版本会自动添加前缀。

args 是一个要添加到 URI 的查询字符串参数表。

如果 body 是一个表或布尔值，它会在发送之前自动进行 JSON 编码。 否则，任何 lua-resty-http 接受的作为主体输入的内容都是有效的。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

delete

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

对提供的路径执行 DELETE 请求。API 版本会自动添加前缀。

args 是一个要添加到 URI 的查询字符串参数表。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

get_client_body_reader

代理方法到 lua-resty-http

键值助手

这些方法会自动添加前缀 /v1/kv，只需传递实际的键。 Base64 编码的值会自动解码。

get_key

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

检索一个 Consul KV 键。值会进行 Base64 解码。

args 是一个要添加到 URI 的查询字符串参数表。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

put_key

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

创建或更新一个 KV 键。

args 是一个要添加到 URI 的查询字符串参数表。

如果 value 是一个表或布尔值，它会在发送之前自动进行 JSON 编码。 否则，任何 lua-resty-http 接受的作为主体输入的内容都是有效的。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

delete

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

删除一个 KV 条目。

args 是一个要添加到 URI 的查询字符串参数表。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

list_keys

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

检索 KV 存储中的所有键。可选地在 prefix 内。

args 是一个要添加到 URI 的查询字符串参数表。 keys 始终作为查询字符串参数设置。

返回一个 lua-resty-http 响应对象。 在出错时返回 nil 和错误消息。

事务助手

txn

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

对 /v1/txn API 端点执行 PUT 请求，使用提供的有效负载。

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

您可以在 nginx-module-consul 的 GitHub 仓库 中找到此模块的其他配置提示和文档。