etcd client module.
Lua
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
rockspecs
test
README.md
etcd.lua

README.md

lua-etcd

etcd client module for Lua.
this module supports etcd API v2.


Dependencies

Installation

luarocks install etcd --from=http://mah0x211.github.io/rocks/

Built-in module

  • etcd.luasocket is luasocket based client.
local Etcd = require('etcd.luasocket');

Related module

Create client object

cli, err = Etcd.new( [option:table] )

local Etcd = require('etcd.luasocket');
local cli, err = Etcd.new();

Parameters

  • option:table

    • host: string - default http://127.0.0.1:4001
    • peer: string - default http://127.0.0.1:7001
    • ttl: int - default -1
      default ttl for key operation. set -1 to disable ttl.
    • prefix: string
      append this prefix path string to key operation url '/v2/keys'.

    etcd.luasocket module option

    • timeout: int
      request timeout seconds.

Returns

  1. cli: client object.
  2. err: error string.

About the return values of client methods.

client methods returns either a HTTP Response Entity or an error string.

a HTTP Response Entity contains the following fields except 408 timeout status;

  • status: number - HTTP status code.
  • header: table - response header if status is not 408 timeout status.
  • body: string or table - response body if status is not 408 timeout status.

Note: a client method will decode a response body as a JSON string if a Content-Type response header value is a application/json.

please refer the etcd API documentaion at - https://github.com/coreos/etcd for more details of a response entity.

Key-value operations

Get the key-value pair

res, err = cli:get( key:string [, consistent:boolean] )

get the value for key.

local inspect = require('util').inspect;
local res, err = cli:get( '/path/to/key' );

print( inspect( { res, err } ) );

Parameters

  • consistent: boolean - read from master if set a true.

Set the key-value pair

res, err = cli:set( key:string, val:JSON encodable value [, ttl:int] )

set a key-value pair.

local inspect = require('util').inspect;
local res, err = cli:set( '/path/to/key', 'val', 10 );

print( inspect( { res, err } ) );

res, err = cli:setnx( key:string, val:JSON encodable value [, ttl:int] )

set a key-value pair if that key does not exist.

local inspect = require('util').inspect;
local res, err = cli:setnx( '/path/to/key', 'val', 10 );

print( inspect( { res, err } ) );

res, err = cli:setx( key:string, val:JSON encodable value [, ttl:int [, modifiedIndex:uint] ] )

set a key-value pair when that key is exists.

local inspect = require('util').inspect;
local res, err = cli:setx( '/path/to/key', 'val', 10 );

print( inspect( { res, err } ) );

Parameters

  • modifiedIndex: uint - this argument to use to the prevIndex query of atomic operation.
local inspect = require('util').inspect;
local res, err = cli:get( '/path/to/key' );

-- this operation will be failed if the `modifiedIndex` of specified key has already been updated by another client.
res, err = cli:setx( '/path/to/key', 'val', 10, res.body.node.modifiedIndex );
print( inspect( { res, err } ) );

Delete the key-value pair

res, err = cli:delete( key:string [, val:JSON encodable value [, modifiedIndex:uint] ] )

delete a key-value pair.

local inspect = require('util').inspect;
local res, err = cli:delete( '/path/to/key' );

print( inspect( { res, err } ) );

Parameters

  • val: JSON encodable value - this argument to use to the prevValue query of atomic operation.
  • modifiedIndex: uint - this argument to use to the prevIndex query of atomic operation.
local inspect = require('util').inspect;
local res, err = cli:get( '/path/to/key' );

-- delete key-value pair if both of `value` and `modifiedIndex` has matched to the passed arguments
res, err = cli:delete( '/path/to/key', res.body.node.value, res.body.node.modifiedIndex );

-- delete key-value pair if `value` has matched to the passed value
res, err = cli:delete( '/path/to/key', res.body.node.value );

-- delete key-value pair if `modifiedIndex` has matched to the passed modifiedIndex
res, err = cli:delete( '/path/to/key', nil, res.body.node.modifiedIndex );

print( inspect( { res, err } ) );

Wait the update of key.

res, err = cli:wait( key:string [, modifiedIndex:uint [, timeout:uint] ] )

local inspect = require('util').inspect;
local res, err = cli:wait( '/path/to/key' );

print( inspect( { res, err } ) );

Parameters

  • modifiedIndex: uint - this argument to use to the prevIndex query of atomic operation.
  • timeout: uint - request timeout seconds. set 0 to disable timeout.
local inspect = require('util').inspect;
local res, err = cli:get( '/path/to/key' );

-- Wait forever the update of key until that modifiedIndex of key has changed to modifiedIndex + 1
res, err = cli:wait( '/path/to/key', res.body.node.modifiedIndex + 1, 0 );

-- Wait for 10 seconds the update of key until that modifiedIndex of key has changed to modifiedIndex + 2
res, err = cli:wait( '/path/to/key', res.body.node.modifiedIndex + 2, 10 );

print( inspect( { res, err } ) );

Directory operations

Read the directory

res, err = cli:readdir( key:string [, recursive:boolean [, consistent:boolean] ] )

local inspect = require('util').inspect;
local res, err = cli:readdir( '/path/to/dir' );

print( inspect( { res, err } ) );

Parameters

  • recursive: boolean - get all the contents under a directory.
  • consistent: boolean - read from master if set a true.

Create the directory

res, err = cli:mkdir( key:string [, ttl:int] )

create a directory.

local inspect = require('util').inspect;
local res, err = cli:mkdir( '/path/to/dir', 10 );

print( inspect( { res, err } ) );

res, err = cli:mkdirnx( key:string [, ttl:int] )

create a directory if that directory does not exist.

local inspect = require('util').inspect;
local res, err = cli:mkdirnx( '/path/to/dir', 10 );

print( inspect( { res, err } ) );

Remove the directory

res, err = cli:rmdir( key:string [, recursive:boolean] )

local inspect = require('util').inspect;
local res, err = cli:readdir( '/path/to/dir' );

print( inspect( { res, err } ) );

Parameters

  • recursive: boolean - remove all the contents under a directory.

Wait the update of directory

res, err = cli:waitdir( key:string [, modifiedIndex:uint [, timeout:uint] ] )

local inspect = require('util').inspect;
local res, err = cli:wait( '/path/to/dir' );

print( inspect( { res, err } ) );

Parameters

  • modifiedIndex: uint - this argument to use to the prevIndex query of atomic operation.
  • timeout: uint - request timeout seconds. set 0 to disable timeout.

Push a value into the directory

res, err = cli:push( key:string, val:JSON encodable value [, ttl:int] )

push a value into the specified directory.

local inspect = require('util').inspect;
local res, err = cli:mkdir( '/path/to/dir' );

res, err = cli:push( '/path/to/dir', 'val', 10 );

print( inspect( { res, err } ) );

Helper method

res, err = cli:setTTL( key:string, ttl:int )

update the TTL value of specified key with the atomic operation.

local inspect = require('util').inspect;
local res, err = cli:setTTL( '/path/to/key', 10 );

print( inspect( { res, err } ) );

Get or set the cluster information

the following client methods to use to get or set the cluster informations.

Get the etcd version

res, err = cli:version()

getting the etcd version info.

local inspect = require('util').inspect;
local res, err = cli:version();

print( inspect( { res, err } ) );

Get the cluster statistics

the following client methods to use to get the cluster statistics information.

res, err = cli:statsLeader()

getting the leader statistics info.

local inspect = require('util').inspect;
local res, err = cli:statsLeader();

print( inspect( { res, err } ) );

res, err = cli:statsSelf()

getting the self statistics info.

local inspect = require('util').inspect;
local res, err = cli:statsSelf();

print( inspect( { res, err } ) );

res, err = cli:statsStore()

getting the store statistics info.

local inspect = require('util').inspect;
local res, err = cli:statsSelf();

print( inspect( { res, err } ) );

Get or set the cluster configuration

res, err = cli:adminConfig()

getting the list of all machines in the cluster.

local inspect = require('util').inspect;
local res, err = cli:config();

print( inspect( { res, err } ) );

res, err = cli:setAdminConfig()

getting the list of all machines in the cluster.

local inspect = require('util').inspect;
local res, err = cli:setConfig();

print( inspect( { res, err } ) );

Get or remove the machines

res, err = cli:adminMachines()

getting the list of all machines in the cluster.

local inspect = require('util').inspect;
local res, err = cli:machines();

print( inspect( { res, err } ) );

res, err = cli:removeAdminMachines( name:string )

removing the machine from the cluster.

local inspect = require('util').inspect;
-- get list of all machines
local res, err = cli:machines();
local name;

-- lookup the machine name to remove.
name = -- your code...

res, err = cli:removeMachine( name );

print( inspect( { res, err } ) );