NAME

Net::Etcd - etcd v3 REST API.

SYNOPSIS

Etcd v3.1.0 or greater is required.   To use the v3 API make sure to set environment
variable ETCDCTL_API=3.  Precompiled binaries can be downloaded at https://github.com/etcd-io/etcd/releases.

$etcd = Net::Etcd->new(); # host: 127.0.0.1 port: 2379
$etcd = Net::Etcd->new({ host => $host, port => $port, ssl => 1 });

# put key
$put_key = $etcd->put({ key =>'foo1', value => 'bar' });

# check for success of a transaction
$put_key->is_success;

# get single key
$key = $etcd->range({ key =>'test0' });

# return single key value or the first in a list.
$key->get_value

# get range of keys
$range = $etcd->range({ key =>'test0', range_end => 'test100' });

# return array { key => value } pairs from range request.
my @users = $range->all

# delete single key
$etcd->deleterange({ key => 'test0' });

# watch key range, streaming.
$watch = $etcd->watch( { key => 'foo', range_end => 'fop'}, sub {
    my ($result) =  @_;
    print STDERR Dumper($result);
})->create;

# create/grant 20 second lease
$etcd->lease( { ID => 7587821338341002662, TTL => 20 } )->grant;

# attach lease to put
$etcd->put( { key => 'foo2', value => 'bar2', lease => 7587821338341002662 } );

# add new user
$etcd->user( { name => 'samba', password => 'foo' } )->add;

# add new user role
$role = $etcd->role( { name => 'myrole' } )->add;

# grant read permission for the foo key to myrole
$etcd->role_perm( { name => 'myrole', key => 'foo', permType => 'READWRITE' } )->grant;

# grant role
$etcd->user_role( { user => 'samba', role => 'myrole' } )->grant;

# defrag member's backend database
$defrag = $etcd->maintenance()->defragment;
print "Defrag request complete!" if $defrag->is_success;

# member version
$v = $etcd->version;

# list members
$etcd->member()->list;

DESCRIPTION

Net::Etcd is object oriented interface to the v3 REST API provided by the etcd grpc-gateway.

ACCESSORS

host

The etcd host. Defaults to 127.0.0.1

port

Default 2379.

name

Username for authentication, defaults to $ENV{ETCD_CLIENT_USERNAME}

password

Authentication credentials, defaults to $ENV{ETCD_CLIENT_PASSWORD}

ca_file

Path to ca_file, defaults to $ENV{ETCD_CLIENT_CA_FILE}

key_file

Path to key_file, defaults to $ENV{ETCD_CLIENT_KEY_FILE}

cert_file

Path to cert_file, defaults to $ENV{ETCD_CLIENT_CERT_FILE}

cacert

Path to cacert, defaults to $ENV{ETCD_CLIENT_CACERT_FILE}.

ssl

To enable set to 1

api_version

defaults to /v3beta

api_path

The full api path. Defaults to http://127.0.0.1:2379/v3alpha

auth_token

The token that is passed during authentication. This is generated during the authentication process and stored until no longer valid or username is changed.

PUBLIC METHODS

version

Returns the etcd member version

$etcd->version()

watch

See Net::Etcd::Watch

$etcd->watch({ key =>'foo', range_end => 'fop' })

role

See Net::Etcd::Auth::Role

$etcd->role({ role => 'foo' });

role_perm

See Net::Etcd::Auth::RolePermission

Grants or revoke permission of a specified key or range to a specified role.

$etcd->role_perm(
    { name => 'myrole', key => 'bar', permType => 'READ', prefix => 1 } )->grant;

user_role

See Net::Etcd::User::Role

$etcd->user_role({ name => 'samba', role => 'foo' });

auth

See Net::Etcd::Auth

$etcd->auth({ name => 'samba', password => 'foo' })->authenticate;
$etcd->auth()->enable;
$etcd->auth()->disable

lease

See Net::Etcd::Lease

$etcd->lease( { ID => 7587821338341002662, TTL => 20 } )->grant;

maintenance

See Net::Etcd::Maintenance

$etcd->maintenance()->snapshot

member

See Net::Etcd::Member

$etcd->member()->list

user

See Net::Etcd::User

$etcd->user( { name => 'samba', password => 'foo' } )->add;

put

See Net::Etcd::KV::Put

$etcd->put({ key =>'foo1', value => 'bar' });

deleterange

See Net::Etcd::KV::DeleteRange

$etcd->deleterange({ key=>'test0' });

range

See Net::Etcd::KV::Range

$etcd->range({ key =>'test0', range_end => 'test100' });

txn

See Net::Etcd::KV::Txn

$etcd->txn({ compare => \@compare, success => \@op });

op

See Net::Etcd::KV::Op

$etcd->op({ request_put => $put });
$etcd->op({ request_delete_range => $range });

compare

See Net::Etcd::KV::Compare

$etcd->compare( { key => 'foo', result => 'EQUAL', target => 'VALUE', value => 'baz' });
$etcd->compare( { key => 'foo', target => 'CREATE', result => 'NOT_EQUAL', create_revision => '2' });

configuration

Initialize configuration checks to see if etcd is installed locally.

AUTHOR

Sam Batschelet (hexfusion)

CONTRIBUTORS

Ananth Kavuri

Michael Fung

ACKNOWLEDGEMENTS

The etcd developers and community.

CAVEATS

The etcd v3 API is in heavy development and can change at anytime please see api_reference_v3 for latest details.

Authentication provided by this module will only work with etcd v3.3.0+

LICENSE AND COPYRIGHT

Copyright 2018 Sam Batschelet (hexfusion).

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.