syntax: cli, err = etcd.new([option:table])
option:tableprotocol: string -v3.http_host: string - defaulthttp://127.0.0.1:2379ttl: int - default-1default ttl for key operation. set -1 to disable ttl.key_prefix: string append this prefix path string to key operation url.timeout: int default request timeout seconds.api_prefix: string to suit etcd v3 api gateway. it will autofill by fetching etcd version if this option empty.ssl_verify: boolean - whether to verify the etcd certificate when originating TLS connection with etcd (if you want to communicate to etcd with TLS connection, usehttpsscheme in yourhttp_host), default is `true.
The client methods returns either a etcd object or an error string.
local cli, err = require("resty.etcd").new({protocol = "v3"})Please refer the etcd API documentaion at - https://github.com/coreos/etcd for more details.
syntax: res, err = cli:get(key:string[, opts])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.revision: (int) revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.
Gets the value for key.
local res, err = cli:get('/path/to/key')syntax: res, err = cli:set(key:string, val:JSON value [, opts:table])
key: string value.val: the value which can be encoded via JSON.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.lease: (int) the lease ID to associate with the key in the key-value store.prev_kv: (bool) If prev_kv is set, etcd gets the previous key-value pair before changing it. The previous key-value pair will be returned in the put response.ignore_value: (bool) If ignore_value is set, etcd updates the key using its current value. Returns an error if the key does not exist.ignore_lease: (bool) If ignore_lease is set, etcd updates the key using its current lease. Returns an error if the key does not exist.
Set a key-value pair.
local res, err = cli:set('/path/to/key', 'val', 10)syntax: res, err = cli:setnx(key:string, val:JSON value [, opts:table])
key: string value.val: the value which can be encoded via JSON.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.
Set a key-value pair if that key does not exist.
local res, err = cli:setnx('/path/to/key', 'val', 10)syntax: res, err = cli:setx(key:string, val:JSON value [, opts:table])
key: string value.val: the value which can be encoded via JSON.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.
Set a key-value pair when that key is exists.
local res, err = cli:setx('/path/to/key', 'val', 10)syntax: res, err = cli:delete(key:string [, opts:table])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.prev_kv: (bool) If prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.
Deletes a key-value pair.
local res, err = cli:delete('/path/to/key')syntax: res, err = cli:watch(key:string [, opts:table])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.start_revision: (int) start_revision is an optional revision to watch from (inclusive). No start_revision is "now".progress_notify: (bool) progress_notify is set so that the etcd server will periodically send a WatchResponse with no events to the new watcher if there are no recent events.filters: (slice of (enum FilterType {NOPUT = 0;NODELETE = 1;})) filters filter the events at server side before it sends back to the watcher.prev_kv: (bool) If prev_kv is set, created watcher gets the previous KV before the event happens. If the previous KV is already compacted, nothing will be returned.watch_id: (int) If watch_id is provided and non-zero, it will be assigned to this watcher. Since creating a watcher in etcd is not a synchronous operation, this can be used ensure that ordering is correct when creating multiple watchers on the same stream. Creating a watcher with an ID already in use on the stream will cause an error to be returned.fragment: (bool) fragment enables splitting large revisions into multiple watch responses.need_cancel: (bool) if watch need to be cancel, watch would return http_cli for further cancelation. See watchcancel for detail.
Watch the update of key.
local res, err = cli:watch('/path/to/key')syntax: res, err = cli:watchcancel(http_cli:table)
http_cli: the http client needs to revoke.
Cancel the watch before it got expired. Need to set need_cancel to get the http client for cancelation.
local res, err, http_cli = cli:watch('/path/to/key', {need_cancel = true})
res = cli:watchcancel(http_cli)syntax: res, err = cli:readdir(dir:string [, opts:table])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.revision: (int) revision is the point-in-time of the key-value store to use for the range. If revision is less or equal to zero, the range is over the newest key-value store. If the revision has been compacted, ErrCompacted is returned as a response.limit: (int) limit is a limit on the number of keys returned for the request. When limit is set to 0, it is treated as no limit.sort_order: (int [SortNone:0, SortAscend:1, SortDescend:2]) sort_order is the order for returned sorted results.sort_target: (int [SortByKey:0, SortByVersion:1, SortByCreateRevision:2, SortByModRevision:3, SortByValue:4]) sort_target is the key-value field to use for sorting.keys_only: (bool) keys_only when set returns only the keys and not the values.count_only: (bool) count_only when set returns only the count of the keys in the range.
Read the directory.
local res, err = cli:readdir('/path/to/dir')syntax: res, err = cli:watchdir(dir:string [, opts:table])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.start_revision: (int) start_revision is an optional revision to watch from (inclusive). No start_revision is "now".progress_notify: (bool) progress_notify is set so that the etcd server will periodically send a WatchResponse with no events to the new watcher if there are no recent events.filters: (slice of [enum FilterType {NOPUT = 0;NODELETE = 1;}]) filters filter the events at server side before it sends back to the watcher.prev_kv: (bool) If prev_kv is set, created watcher gets the previous KV before the event happens. If the previous KV is already compacted, nothing will be returned.watch_id: (int) If watch_id is provided and non-zero, it will be assigned to this watcher. Since creating a watcher in etcd is not a synchronous operation, this can be used ensure that ordering is correct when creating multiple watchers on the same stream. Creating a watcher with an ID already in use on the stream will cause an error to be returned.fragment: (bool) fragment enables splitting large revisions into multiple watch responses.
Watch the update of directory.
local res, err = cli:watchdir('/path/to/dir')syntax: res, err = cli:rmdir(dir:string [, opts:table])
key: string value.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.prev_kv: (bool) If prev_kv is set, etcd gets the previous key-value pairs before deleting it. The previous key-value pairs will be returned in the delete response.
Remove the directory
local res, err = cli:rmdir('/path/to/dir')syntax: res, err = cli:txn(compare:array, success:array, failure:array [, opts:table])
compare: array of table.success: array of table.failure: array of table.opts: optional options.timeout: (int) request timeout seconds. set 0 to disable timeout.
Transaction
local compare = {}
compare[1] = {}
compare[1].target = "CREATE"
compare[1].key = encode_base64("test")
compare[1].createRevision = 0
local success = {}
success[1] = {}
success[1].requestPut = {}
success[1].requestPut.key = encode_base64("test")
local res, err = cli:txn(compare, success, nil)syntax: res, err = cli:version()
Gets the etcd version info.
syntax: res, err = cli:grant(TTL:int [, ID:int])
TTL: advisory time-to-live in seconds.ID: the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.
Creates a lease which expires if the server does not receive a keepalive within a given time to live period. All keys attached to the lease will be expired and deleted if the lease expires. Each expired key generates a delete event in the event history.
-- grant a lease with 5 second TTL
local res, err = cli:grant(5)
-- attach key to lease, whose ID would be contained in res
local data, err = etcd:set('/path/to/key', 'val', {lease = res.body.ID})syntax: res, err = cli:revoke(ID:int)
ID: the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.
Revokes a lease. All keys attached to the lease will expire and be deleted.
local res, err = cli:grant(5)
local data, err = etcd:set('/path/to/key', 'val', {lease = res.body.ID})
local data, err = etcd:revoke(res.body.ID)
local data, err = cli:get('/path/to/key')
-- responce would contains no kvssyntax: res, err = cli:keepalive(ID:int)
ID: the lease ID for the lease to keep alive.
Keeps the lease alive by streaming keep alive requests from the client to the server and streaming keep alive responses from the server to the client.
syntax: res, err = cli:timetolive(ID:int [, keys: bool])
ID: the lease ID for the lease.keys: if true, query all the keys attached to this lease.
Retrieves lease information.
syntax: res, err = cli:leases()
Lists all existing leases.