Consul - Client library for consul
use Consul; my $consul = Consul->new; say $consul->status->leader; # shortcut to single API my $status = Consul->status; say $status->leader;
This is a client library for accessing and manipulating data in a Consul cluster. It targets the Consul v1 HTTP API.
This module is quite low-level. You're expected to have a good understanding of Consul and its API to understand the methods this module provides. See "SEE ALSO" for further reading.
This is still under development. The documentation isn't all there yet (in particular about the return types) and a couple of APIs aren't implemented. It's still very useful and I don't expect huge changes, but please take care when upgrading. Open an issue if there's something you need that isn't here and I'll get right on it!
my $consul = Consul->new( %args );
This constructor returns a new Consul client object. Valid arguments include:
host
Hostname or IP address of an Consul server (default: 127.0.0.1)
127.0.0.1
port
Port where the Consul server is listening (default: 8500)
8500
ssl
Use SSL/TLS (ie HTTPS) when talking to the Consul server (default: off)
timeout
Request timeout. If a request to Consul takes longer that this, the endpoint method will fail (default: 15).
token
Consul ACL token. This is used to set the X-Consul-Token HTTP header. Typically Consul agents are pre-configured with a default ACL token, or ACLs are not enabled at all, so this option only needs to be set in certain cases.
X-Consul-Token
request_cb
A callback to an alternative method to make the actual HTTP request. The callback is of the form:
sub { my ($self, $req) = @_; ... do HTTP call $req->callback->(Consul::Response->new(...)); }
$req is a Consul::Request object, and has the following attributes:
$req
Consul::Request
method
The HTTP method for the request.
url
The complete URL to request. This is fully formed, and includes scheme, host, port and query parameters. You shouldn't need to touch it.
headers
A Hash::MultiValue object containing any headers that should be added to the request.
content
The body content for the request.
callback
A callback to call when the request is completed. It takes a single Consul::Response object as its parameter.
Consul::Response
args
A hashref containing the original arguments passed in to the endpoint method.
The callback function should be called with a Consul::Response object containing the values returned by the Consul server in response to the request. Create one with new, passing the following attributes:
new
status
The integer status code.
reason
The status reason phrase.
A Hash::MultiValue containing the response headers.
Any body content returned in the response.
request
The Consul::Request object passed to the callback.
Consul itself provides a default request_cb that uses HTTP::Tiny to make calls to the server. If you provide one, you should honour the value of the timeout argument.
request_cb can be used in conjunction with the cb option to all API method endpoints to get asynchronous behaviour. It's recommended however that you don't use this directly, but rather use a module like AnyEvent::Consul to take care of that for you.
cb
If you just want to use this module to make simple calls to your Consul cluster, you can ignore this option entirely.
error_cb
A callback to an alternative method to handle internal errors (usually HTTP errors). The callback is of the form:
sub { my ($err) = @_; ... output $err ... }
The default callback simply calls croak.
croak
Individual API endpoints are implemented in separate modules. The following methods will return a context objects for the named API. Alternatively, you can request an API context directly from the Consul package. In that case, Consul->new is called implicitly.
Consul->new
# these are equivalent my $agent = Consul->new( %args )->agent; my $agent = Consul->agent( %args );
Key/value store API. See Consul::API::KV.
Agent API. See Consul::API::Agent.
Catalog (nodes and services) API. See Consul::API::Catalog.
Health check API. See Consul::API::Health.
Sessions API. See Consul::API::Session.
Access control API. See Consul::API::ACL.
User event API. See Consul::API::Event.
System status API. See Consul::API::Status.
All API methods implemented by the endpoints can take a number of arguments. Most of those are documented in the endpoint documentation. There are however some that are common to all methods:
A callback to call with the results of the method. Without this, the results are returned from the method, but only if request_cb is synchronous. If an asynchronous request_cb is used without a cb being passed to the method, the method return value is undefined.
A callback to an alternative method to handle internal errors (usually HTTP errors). errors). The callback is of the form:
The default callback calls the error_cb for the API object itself, which by default, simply calls croak.
Some Consul API endpoints support a feature called a "blocking query". These endpoints allow long-polling for changes, and support some extra information about the server state, including the Raft index, in the response headers.
The corresponding endpoint methods, when called in array context, will return a second value. This is an object with three methods, index, last_contact and known_leader, corresponding to the similarly-named header fields. You can use these to set up state watches, CAS writes, and so on.
index
last_contact
known_leader
See the Consul API docs for more information.
AnyEvent::Consul - a wrapper providing asynchronous operation
https://www.consul.io/docs/agent/http.html - Consul HTTP API documentation
Please report any bugs or feature requests through the issue tracker at https://github.com/robn/Consul/issues. You will be notified automatically of any progress on your issue.
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/robn/Consul
git clone https://github.com/robn/Consul.git
Rob N ★ <robn@robn.io>
Aran Deltac <bluefeet@gmail.com>
Michael McClimon
This software is copyright (c) 2015 by Rob N ★.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Consul, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Consul
CPAN shell
perl -MCPAN -e shell install Consul
For more information on module installation, please visit the detailed CPAN module installation guide.