lua-resty-consul

Library to interface with the consul HTTP API from ngx_lua

Table of Contents

• Overview
• Dependencies
• Methods
  • new
  • get
  • get_decoded
  • get_json_decoded
  • get_keys
  • get_values
  • get_values_decoded
  • get_values_json_decoded
  • put
  • delete
  • get_client_body_reader
  • txn

Overview

local resty_consul = require('resty.consul')
local consul = resty_consul:new({
        host = '10.10.10.10',
        port = 8500
    })

local ok, err = consul:put('/kv/foobar', 'My key value!')
if not ok then
    ngx.log(ngx.ERR, err)
end

local ok, err = consul:put('/kv/some_json', { msg = 'This will be json encoded'})
if not ok then
    ngx.log(ngx.ERR, err)
end

local res, err = consul:get('/kv/foobar')
if not res then
    ngx.log(ngx.ERR, err)
end
ngx.say(res[1].Value) -- Prints "TXkga2V5IHZhbHVlIQo="

local res, err = consul:get_decoded('/kv/foobar')
if not res then
    ngx.log(ngx.ERR, err)
end
ngx.say(res[1].Value) -- Prints "My key value!"

local res, err = consul:get_json_decoded('/kv/some_json')
if not res then
    ngx.log(ngx.ERR, err)
end
if type(res[1].Value) == 'table' then
    ngx.say(res[1].Value.msg) -- Prints "This will be json encoded"
else
    ngx.log(ngx.ERR, "Failed to decode value :(")
end


local args={recurse="true"}
local key='/kv/some'
local res, err = consul:get_keys(key, args)
--local res, err = consul:get_values(key, args)
--local res, err = consul:get_values_decoded(key, args)
--local res, err = consul:get_values_json_decoded(key, args)
if not res then                 -- Prints "This will be return a list"
    ngx.log(ngx.ERR, err)
end            
for k,v in pairs(res)
do
  if type(v) == "string" then
    ngx.log(ngx.ERR,"string:",k,v)
  else
    ngx.log(ngx.ERR,"json:",k,cjson.encode(v))
  end
end      

/v1/txn

Available in Consul 0.7 and later, this endpoint manages updates or fetches of multiple keys inside a single, atomic transaction. You can find more info inside official docs.

ngx.req.read_body()
local key_value = ngx.req.get_body_data()
local res, err = consul:txn_decoded_json('set', key_value)
if not ok then
    ngx.log(ngx.ERR, err)
    ngx.status = ngx.HTTP_INTERNAL_SERVER_ERROR
    ngx.say(err)
else
    ngx.status = ngx.HTTP_OK
    ngx.say(res)
end

ngx.req.read_body()
local verb_key_value = ngx.req.get_body_data()
local res, err = consul:txn_multi(verb_key_value)
if not ok then
    ngx.log(ngx.ERR, err)
    ngx.status = ngx.HTTP_INTERNAL_SERVER_ERROR
    ngx.say(err)
else
    ngx.status = ngx.HTTP_OK
    ngx.say(res)
end

Dependencies

• lua-resty-http

Methods

new

syntax: client = consul:new(opts?)

Create a new consul client. opts is a table setting the following options:

• host Defaults to 127.0.0.1
• port Defaults to 8500
• connect_timeout Connection timeout in ms. Defaults to 60s
• read_timeout Read timeout in ms. Defaults to 60s

get

syntax: res, headers = consul:get(key, opts?)

Performs a GET request against the provided key. API Version is automatically prepended.

e.g. to get the value of a key at http://my.consul.server/v1/kv/foobar you would call consul:get('/kv/foobar')

opts is hash of query string parameters to add to the URI.

The wait query string param is a special case, it must be passed in as an number not as a string with 's' appended.

Returns a table representing the response from Consul and a second table of the Consul specific headers X-Consul-Lastcontact, X-Consul-KnownLeader and X-Consul-Index.

On error returns nil and an error message.

get_decoded

syntax: res, headers = consul:get_decoded(key, opts?)

Wrapper on the get method, but performs base64 decode on the value field in the Consul response

get_json_decoded

syntax: res, headers = consul:get_json_decoded(key, opts?)

Wrapper on the get method, but performs base64 decode on the value field in the Consul response and then attempts to parse the value as json.

get_keys

syntax: res, headers = consul:get_keys(key, opts?)

Wrapper on the get method, but check the value field in the Consul response and return the key whose value is not null. when used, the opts arg must be set {recurse="true"}.

get_values

syntax: res, headers = consul:get_values(key, opts?)

Wrapper on the get method, but check the value field in the Consul response and return key and value pair, exclude the key whose value is null. when used, the opts arg must be set {recurse="true"}.

get_values_decoded

syntax: res, headers = consul:get_values_decoded(key, opts?)

similar to get_values, but the value need to decoded.

get_values_json_decoded

syntax: res, headers = consul:get_values_json_decoded(key, opts?)

similar to get_values_decoded, but the value need to deserialize additionally.

put

syntax: res, err = consul:put(key, value, opts?)

Performs a PUT request against the provided key with provided value. API Version is automatically prepended.

opts is hash of query string parameters to add to the URI.

If value is a table or boolean value it is automatically json encoded before being sent.

Otherwise anything that lua-resty-http accepts as a body input is valid.

On a 200 response returns the response body if there is one or a boolean true.

On a non-200 response returns nil and the response body.

delete

syntax: ok, err = consul:delete(key, value, recurse?)

Performs a DELETE request against the provided key.

recurse defaults to false.

Returns a boolean true if the response is 200.

Otherwise a table containing status, body and headers as well as the error from lua-resty-http

get_client_body_reader

Proxy method to lua-resty-http

txn

syntax: res, err = consul:txn(verb, key_value, opts?)

syntax: res, err = consul:txn_json(verb, key_value, opts?)

syntax: res, err = consul:txn_decoded(verb, key_value, opts?)

syntax: res, err = consul:txn_decoded_json(verb, key_value, opts?)

Performs a PUT request with provided verb and key_value inside JSON body. API Version and txn are automatically prepended.

key_value must be JSON, required and optional keys for every verb (type of operations) can be found in this table

e.g. to set new values you would call

consul:txn('set', '[{"Value":"Value_1","Key":"Key_1"},{"Value":"Value_2","Key":"Key_2"}]'),

to get values you would call

consul:txn('get', '[{"Key":"Key_1"},{"Key":"Key_2"}]')

opts is hash of query string parameters to add to the URI.

All four methods create request the same way, response is different:

• txn return Lua table
• txn_json returns JSON string
• txn_decoded returns Lua table with decoded Value
• txn_decoded_json returns JSON string with decoded Value

On error returns nil and an error message.

syntax: res, err = consul:txn_multi(verb_key_value, opts?)

Performs a PUT request with provided verb_key_value inside JSON body. You can execute multiple operations.

e.g. to run set and get inside one request one would call consul:txn_multi('[{"Verb":"set","Value":"Value_1","Key":"Key_1"},{"Verb":"get","Key":"Key_2"}]')

Returns Lua table with Base64 encoded Value.

On error returns nil and an error message.