This is a Consul client.
See the official HTTP API docs for more information.
Initialize a new Consul client.
Options
- host (String, default: 127.0.0.1): agent address
- port (String, default: 8500): agent HTTP(S) port
- secure (Boolean, default: false): enable HTTPS
- ca (String[], optional): array of strings or Buffers of trusted certificates in PEM format
- defaults (Object, optional): default options for method calls
- promisify (Boolean|Function, optional): convert callback methods to promises
Usage
var consul = require('consul')();
All callback methods have the following signature function(err, data, res)
.
- err (Error, optional): set if there was an error, otherwise falsy
- data (Object, optional): response data if any, otherwise
undefined
- res (http.IncomingMessage, optional): HTTP response object with additional
body
property. This might not exist whenerr
is set. Thebody
property can be a decoded object, string, or Buffer.
Promise support can be enabled by setting promisify
to true
in Node >= 0.12
or passing a wrapper (ex: bluebird.fromCallback
) in older versions.
If you need access to the res
object you can create a custom wrapper (see example below).
These options will be passed along with any method call, although only certain endpoints support them. See the HTTP API for more information.
- dc (String, optional): datacenter (defaults to local for agent)
- wan (Boolean, default: false): return WAN members instead of LAN members
- consistent (Boolean, default: false): require strong consistency
- stale (Boolean, default: false): use whatever is available, can be arbitrarily stale
- index (String, optional): used with
ModifyIndex
to block and wait for changes - wait (String, optional): limit how long to wait for changes (ex:
5m
), used with index - token (String, optional): ACL token
These options work for all methods.
- ctx (EventEmitter, optional): emit
cancel
to abort request - timeout (Number, optional): number of milliseconds before request is aborted
Creates a new token with policy.
Options
- name (String, optional): human readable name for the token
- type (String, enum: client, management; default: client): type of token
- rules (String, optional): string encoded HCL or JSON
Usage
consul.acl.create(function(err, result) {
if (err) throw err;
});
Result
{
"ID": "b1f4c10e-b61b-e1de-de95-218c9fefdd3e"
}
Update the policy of a token.
Options
- id (String): token ID
- name (String, optional): human readable name for the token
- type (String, enum: client, management; default: client): type of token
- rules (String, optional): string encoded HCL or JSON
Usage
consul.acl.update({ id: '63e1d82e-f718-eb92-3b7d-61f0c71d45b4', name: 'test' }, function(err) {
if (err) throw err;
});
Destroys a given token.
Options
- id (String): token ID
Usage
consul.acl.destroy('b1f4c10e-b61b-e1de-de95-218c9fefdd3e', function(err) {
if (err) throw err;
});
Queries the policy of a given token.
Options
- id (String): token ID
Usage
consul.acl.get('63e1d82e-f718-eb92-3b7d-61f0c71d45b4', function(err, result) {
if (err) throw err;
});
Result
{
"CreateIndex": 7,
"ModifyIndex": 7,
"ID": "63e1d82e-f718-eb92-3b7d-61f0c71d45b4",
"Name": "Read only",
"Type": "client",
"Rules": "{\"key\":{\"\":{\"policy\":\"read\"}}}"
}
Creates a new token by cloning an existing token.
Options
- id (String): token ID
Usage
consul.acl.clone('63e1d82e-f718-eb92-3b7d-61f0c71d45b4', function(err) {
if (err) throw err;
});
Result
{
"ID": "9fb8b20b-2636-adbb-9b99-d879df3305ec"
}
Lists all the active tokens.
Usage
consul.acl.list(function(err, result) {
if (err) throw err;
});
Result
[
{
"CreateIndex": 2,
"ModifyIndex": 2,
"ID": "anonymous",
"Name": "Anonymous Token",
"Type": "client",
"Rules": ""
}
{
"CreateIndex": 3,
"ModifyIndex": 3,
"ID": "root",
"Name": "Master Token",
"Type": "management",
"Rules": ""
}
]
Returns the members as seen by the consul agent.
Options
- wan (Boolean, default: false): return WAN members instead of LAN members
Usage
consul.agent.members(function(err, result) {
if (err) throw err;
});
Result
[
{
"Name": "node1",
"Addr": "127.0.0.1",
"Port": 8301,
"Tags": {
"bootstrap": "1",
"build": "0.3.0:441d613e",
"dc": "dc1",
"port": "8300",
"role": "consul",
"vsn": "2",
"vsn_max": "2",
"vsn_min": "1"
},
"Status": 1,
"ProtocolMin": 1,
"ProtocolMax": 2,
"ProtocolCur": 2,
"DelegateMin": 2,
"DelegateMax": 4,
"DelegateCur": 4
}
]
Returns the agent node configuration.
Usage
consul.agent.self(function(err, result) {
if (err) throw err;
});
Result
{
"Config": {
"Bootstrap": true,
"Server": true,
"Datacenter": "dc1",
"DataDir": "/tmp/node1/data",
"DNSRecursor": "",
"DNSConfig": {
"NodeTTL": 0,
"ServiceTTL": null,
"AllowStale": false,
"MaxStale": 5000000000
},
"Domain": "consul.",
"LogLevel": "INFO",
"NodeName": "node1",
"ClientAddr": "127.0.0.1",
"BindAddr": "127.0.0.1",
"AdvertiseAddr": "127.0.0.1",
"Ports": {
"DNS": 8600,
"HTTP": 8500,
"RPC": 8400,
"SerfLan": 8301,
"SerfWan": 8302,
"Server": 8300
},
"LeaveOnTerm": false,
"SkipLeaveOnInt": false,
"StatsiteAddr": "",
"Protocol": 2,
"EnableDebug": false,
"VerifyIncoming": false,
"VerifyOutgoing": false,
"CAFile": "",
"CertFile": "",
"KeyFile": "",
"ServerName": "",
"StartJoin": [],
"UiDir": "",
"PidFile": "/tmp/node1/pid",
"EnableSyslog": false,
"SyslogFacility": "LOCAL0",
"RejoinAfterLeave": false,
"CheckUpdateInterval": 300000000000,
"Revision": "441d613e1bd96254c78c46ee7c1b35c161fc7295+CHANGES",
"Version": "0.3.0",
"VersionPrerelease": ""
},
"Member": {
"Name": "node1",
"Addr": "127.0.0.1",
"Port": 8301,
"Tags": {
"bootstrap": "1",
"build": "0.3.0:441d613e",
"dc": "dc1",
"port": "8300",
"role": "consul",
"vsn": "2",
"vsn_max": "2",
"vsn_min": "1"
},
"Status": 1,
"ProtocolMin": 1,
"ProtocolMax": 2,
"ProtocolCur": 2,
"DelegateMin": 2,
"DelegateMax": 4,
"DelegateCur": 4
}
}
Set node maintenance mode.
Options
- enable (Boolean): maintenance mode enabled
- reason (String, optional): human readable reason for maintenance
Usage
consul.agent.maintenance(true, function(err) {
if (err) throw err;
});
Trigger agent to join a node.
Options
- address (String): node IP address to join
- wan (Boolean, default false): attempt to join using the WAN pool
Usage
consul.agent.join('127.0.0.2', function(err) {
if (err) throw err;
});
Force remove node.
Options
- node (String): node name to remove
Usage
consul.agent.forceLeave('node2', function(err) {
if (err) throw err;
});
Returns the checks the agent is managing.
Usage
consul.agent.check.list(function(err, result) {
if (err) throw err;
});
Result
{
"example": {
"Node": "node1",
"CheckID": "example",
"Name": "example",
"Status": "passing",
"Notes": "This is an example check.",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
}
Registers a new check.
Options
- name (String): check name
- id (String, optional): check ID
- serviceid (String, optional): service ID, associate check with existing service
- http (String): url to test, 2xx passes, 429 warns, and all others fail
- tcp (String): host:port to test, passes if connection is established, fails otherwise
- script (String): path to check script, requires interval
- dockercontainerid (String, optional): Docker container ID to run script
- shell (String, optional): shell in which to run script (currently only supported with Docker)
- interval (String): interval to run check, requires script (ex:
15s
) - timeout (String, optional): timeout for the check (ex:
10s
) - ttl (String): time to live before check must be updated, instead of http/tcp/script and interval (ex:
60s
) - notes (String, optional): human readable description of check
- status (String, optional): initial service status
- deregistercriticalserviceafter (String, optional, Consul 0.7+): timeout after which to automatically deregister service if check remains in critical state
Usage
var check = {
name: 'example',
ttl: '15s',
notes: 'This is an example check.',
};
consul.agent.check.register(check, function(err) {
if (err) throw err;
});
Deregister a check.
Options
- id (String): check ID
Usage
consul.agent.check.deregister('example', function(err) {
if (err) throw err;
});
Mark a test as passing.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
consul.agent.check.pass('example', function(err) {
if (err) throw err;
});
Mark a test as warning.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
consul.agent.check.warn('example', function(err) {
if (err) throw err;
});
Mark a test as critical.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
consul.agent.check.fail('example', function(err) {
if (err) throw err;
});
Returns the services the agent is managing.
Usage
consul.agent.service.list(function(err, result) {
if (err) throw err;
});
Result
{
"example": {
"ID": "example",
"Service": "example",
"Tags": [
"dev",
"web"
],
"Port": 80
}
}
Registers a new service.
Options
- name (String): service name
- id (String, optional): service ID
- tags (String[], optional): service tags
- address (String, optional): service IP address
- port (Integer, optional): service port
- check (Object, optional): service check
- http (String): URL endpoint, requires interval
- tcp (String): host:port to test, passes if connection is established, fails otherwise
- script (String): path to check script, requires interval
- dockercontainerid (String, optional): Docker container ID to run script
- shell (String, optional): shell in which to run script (currently only supported with Docker)
- interval (String): interval to run check, requires script (ex:
15s
) - timeout (String, optional): timeout for the check (ex:
10s
) - ttl (String): time to live before check must be updated, instead of http/tcp/script and interval (ex:
60s
) - notes (String, optional): human readable description of check
- status (String, optional): initial service status
- deregistercriticalserviceafter (String, optional, Consul 0.7+): timeout after which to automatically deregister service if check remains in critical state
- checks (Object[], optional): service checks (see
check
above)
Usage
consul.agent.service.register('example', function(err) {
if (err) throw err;
});
Deregister a service.
Options
- id (String): service ID
Usage
consul.agent.service.deregister('example', function(err) {
if (err) throw err;
});
Set service maintenance mode.
Options
- id (String): service ID
- enable (Boolean): maintenance mode enabled
- reason (String, optional): human readable reason for maintenance
Usage
consul.agent.service.maintenance({ id: 'example', enable: true }, function(err) {
if (err) throw err;
});
Lists known datacenters.
Usage
consul.catalog.datacenters(function(err, result) {
if (err) throw err;
});
Result
[
"dc1"
]
Lists nodes in a given datacenter.
Options
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.catalog.node.list(function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": "node1",
"Address": "127.0.0.1"
}
]
Lists the services provided by a node.
Options
- node (String): node ID
Usage
consul.catalog.node.services('node1', function(err, result) {
if (err) throw err;
});
Result
{
"Node": {
"Node": "node1",
"Address": "127.0.0.1"
},
"Services": {
"consul": {
"ID": "consul",
"Service": "consul",
"Tags": [],
"Port": 8300
},
"example": {
"ID": "example",
"Service": "example",
"Tags": [
"dev",
"web"
],
"Port": 80
}
}
}
Lists services in a given datacenter.
Options
- dc (String): datacenter (defaults to local for agent)
Usage
consul.catalog.service.list(function(err, result) {
if (err) throw err;
});
Result
{
"consul": [],
"example": [
"dev",
"web"
]
}
Lists the nodes in a given service.
Options
- service (String): service name
- dc (String, optional): datacenter (defaults to local for agent)
- tag (String, optional): filter by tag
Usage
consul.catalog.service.nodes('example', function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": "node1",
"Address": "127.0.0.1",
"ServiceID": "example",
"ServiceName": "example",
"ServiceTags": [
"dev",
"web"
],
"ServicePort": 80
}
]
Fires a new user event.
Options
- name (String): event name
- payload (String|Buffer): payload
- node (String, optional): regular expression to filter by node
- service (String, optional): regular expression to filter by service
- tag (String, optional): regular expression to filter by tag
Usage
consul.event.fire('deploy', '53', function(err, result) {
if (err) throw err;
});
Result
{
"ID": "4730953b-3135-7ff2-47a7-9d9fc9c4e5a2",
"Name": "deploy",
"Payload": "53",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 0
}
Lists the most recent events an agent has seen.
Options
- name (String, optional): filter by event name
Usage
consul.event.list('deploy', function(err, result) {
if (err) throw err;
});
Result
[
{
"ID": "4730953b-3135-7ff2-47a7-9d9fc9c4e5a2",
"Name": "deploy",
"Payload": "53",
"NodeFilter": "",
"ServiceFilter": "",
"TagFilter": "",
"Version": 1,
"LTime": 2
}
]
Returns the health info of a node.
Options
- node (String): node
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.health.node('node1', function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": "node1",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "Agent alive and reachable",
"ServiceID": "",
"ServiceName": ""
},
{
"Node": "node1",
"CheckID": "service:example",
"Name": "Service 'example' check",
"Status": "critical",
"Notes": "",
"Output": "",
"ServiceID": "example",
"ServiceName": "example"
}
]
Returns the checks of a service.
Options
- service (String): service name
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.health.checks('example', function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": "node1",
"CheckID": "service:example",
"Name": "Service 'example' check",
"Status": "critical",
"Notes": "",
"Output": "",
"ServiceID": "example",
"ServiceName": "example"
}
]
Returns the nodes and health info of a service.
Options
- service (String): service name
- dc (String, optional): datacenter (defaults to local for agent)
- tag (String, optional): filter by tag
- passing (Boolean, optional): restrict to passing checks
Usage
consul.health.service('example', function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": {
"Node": "node1",
"Address": "127.0.0.1"
},
"Service": {
"ID": "example",
"Service": "example",
"Tags": [],
"Port": 0
},
"Checks": [
{
"Node": "node1",
"CheckID": "service:example",
"Name": "Service 'example' check",
"Status": "critical",
"Notes": "",
"Output": "",
"ServiceID": "example",
"ServiceName": "example"
},
{
"Node": "node1",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "Agent alive and reachable",
"ServiceID": "",
"ServiceName": ""
}
]
}
]
Returns the checks in a given state.
Options
- state (String, enum: any, passing, warning, critical): state
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.health.state('critical', function(err, result) {
if (err) throw err;
});
Result
[
{
"Node": "node1",
"CheckID": "service:example",
"Name": "Service 'example' check",
"Status": "critical",
"Notes": "",
"Output": "",
"ServiceID": "example",
"ServiceName": "example"
}
]
Return key/value (kv) pair(s).
Options
- key (String): path to value
- dc (String, optional): datacenter (defaults to local for agent)
- recurse (Boolean, default: false): return all keys with given key prefix
- index (String, optional): used with
ModifyIndex
to block and wait for changes - wait (String, optional): limit how long to wait for changes (ex:
5m
), used with index - raw (Boolean, optional): return raw value (can't be used with recursive, implies buffer)
- buffer (Boolean, default: false): decode value into Buffer instead of String
Usage
consul.kv.get('hello', function(err, result) {
if (err) throw err;
});
Result
{
"CreateIndex": 6,
"ModifyIndex": 6,
"LockIndex": 0,
"Key": "hello",
"Flags": 0,
"Value": "world"
}
Return keys for a given prefix.
Options
- key (String): path prefix
- dc (String, optional): datacenter (defaults to local for agent)
- separator (String, optional): list keys up to a given separator
Usage
consul.kv.keys('a/', function(err, result) {
if (err) throw err;
});
Result
[
"a/b",
"a/c"
]
Set key/value (kv) pair.
Options
- key (String): key
- value (String|Buffer): value
- dc (String, optional): datacenter (defaults to local for agent)
- flags (Number, optional): unsigned integer opaque to user, can be used by application
- cas (String, optional): use with
ModifyIndex
to do a check-and-set operation - acquire (String, optional): session ID, lock acquisition operation
- release (String, optional): session ID, lock release operation
Usage
consul.kv.set('hello', 'world', function(err, result) {
if (err) throw err;
});
Result
true
Delete key/value (kv) pair(s).
Options
- key (String): key
- dc (String, optional): datacenter (defaults to local for agent)
- recurse (Boolean, default: false): delete all keys with given key prefix
- cas (String, optional): use with
ModifyIndex
to do a check-and-set operation (must be greater than0
)
Usage
consul.kv.del('hello', function(err) {
if (err) throw err;
});
Experimental
Lock a key using the method described in the leader election guide.
Options
- key (String): lock key
- value (String|Buffer, optional): lock value
- session (Object|String, optional): session options
Events
acquire
: lock successfully acquirederror
: lock related errorretry
: lock retry attemptrelease
: lock gracefully released (not always emitted)end
: lock ended (always emitted)
Usage
var lock = consul.lock({ key: 'test' });
lock.on('acquire', function() {
console.log('lock acquired');
lock.release();
});
lock.on('release', function() {
console.log('lock released');
});
lock.on('error', function() {
console.log('lock error:', err);
});
lock.on('end', function(err) {
console.log('lock released or there was a permanent failure');
});
lock.acquire();
Result
lock acquired
lock released
lock released or there was a permanent failure
List prepared query.
Usage
consul.query.list(function(err, result) {
if (err) throw err;
});
Result
[
{
"ID": "422b14b9-874b-4520-bd2e-e149a42b0066",
"Name": "redis",
"Session": "",
"Token": "",
"Template": {
"Type": "",
"Regexp":""
},
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": [
"dc1",
"dc2"
]
},
"OnlyPassing": false,
"Tags": [
"master",
"!experimental"
]
},
"DNS": {
"TTL": "10s"
},
"RaftIndex": {
"CreateIndex": 23,
"ModifyIndex": 42
}
}
]
Create a new prepared query.
Options
- name (String, optional): name that can be used to execute a query instead of using its ID
- session (String, optional): provides a way to automatically remove a prepared query when the given session is invalidated
- token (String, optional): captured ACL Token that is reused as the ACL Token every time the query is executed
- near (String, optional): allows specifying a particular node to sort near based on distance sorting using Network Coordinates
- service.service (String, required): name of the service to query
- service.failover.nearestn (Number, optional): when set the query will be forwarded to up to nearest N other datacenters based on their estimated network round trip time using Network Coordinates from the WAN gossip pool
- service.failover.datacenters (String[], optional): fixed list of remote datacenters to forward the query to if there are no healthy nodes in the local datacenter
- service.onlypassing (Boolean, default: false): filter results to only nodes with a passing state
- service.tags (String[], optional): list of service tags to filter the query results
- ttl.dns (String, optional, ex:
10s
): controls how the TTL is set when query results are served over DNS
Usage
var opts = {
name: 'redis',
service: {
service: 'redis'
onlypassing: true
},
};
consul.query.create(opts, function(err, result) {
if (err) throw err;
});
Result
{
"ID": "422b14b9-874b-4520-bd2e-e149a42b0066"
}
Update existing prepared query.
Options
- query (String, required): ID of the query
And all [create options][query-create].
Usage
var opts = {
query: '422b14b9-874b-4520-bd2e-e149a42b0066',
name: 'redis',
service: {
service: 'redis'
onlypassing: false
},
};
consul.query.update(opts, function(err, result) {
if (err) throw err;
});
Get prepared query.
Options
- query (String, required): ID of the query
Usage
consul.query.get('6119cabf-c052-48fe-9f07-711762e52931', function(err, result) {
if (err) throw err;
});
Result
{
"ID": "6119cabf-c052-48fe-9f07-711762e52931",
"Name": "redis",
"Session": "",
"Token": "",
"Template": {
"Type": "",
"Regexp":""
},
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": [
"dc1",
"dc2"
]
},
"OnlyPassing": false,
"Tags": [
"master",
"!experimental"
]
},
"DNS": {
"TTL": "10s"
},
"RaftIndex": {
"CreateIndex": 23,
"ModifyIndex": 42
}
}
Delete prepared query.
Options
- query (String, required): ID of the query
Usage
consul.query.destroy('422b14b9-874b-4520-bd2e-e149a42b0066', function(err) {
if (err) throw err;
});
Execute prepared query.
Options
- query (String, required): ID of the query
Usage
consul.query.execute('6119cabf-c052-48fe-9f07-711762e52931', function(err) {
if (err) throw err;
});
Result
{
"Service": "redis",
"Nodes": [
{
"Node": {
"Node": "foobar",
"Address": "10.1.10.12",
"TaggedAddresses": {
"lan": "10.1.10.12",
"wan": "10.1.10.12"
}
},
"Service": {
"ID": "redis",
"Service": "redis",
"Tags": null,
"Port": 8000
},
"Checks": [
{
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis"
},
{
"Node": "foobar",
"CheckID": "serfHealth",
"Name": "Serf Health Status",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "",
"ServiceName": ""
}
],
"DNS": {
"TTL": "10s"
},
"Datacenter": "dc3",
"Failovers": 2
}
]
}
Explain prepared query.
Options
- query (String, required): ID of the query
Usage
consul.query.explain('422b14b9-874b-4520-bd2e-e149a42b0066', function(err, result) {
if (err) throw err;
console.log(result);
});
Result
{
"Query": {
"ID": "422b14b9-874b-4520-bd2e-e149a42b0066",
"Name": "redis",
"Session": "",
"Token": "",
"Template": {
"Type": "",
"Regexp":""
},
"Service": {
"Service": "redis",
"Failover": {
"NearestN": 3,
"Datacenters": [
"dc1",
"dc2"
]
},
"OnlyPassing": false,
"Tags": [
"master",
"!experimental"
]
},
"DNS": {
"TTL": "10s"
},
"RaftIndex": {
"CreateIndex": 23,
"ModifyIndex": 42
}
}
}
Create a new session.
Options
- dc (String, optional): datacenter (defaults to local for agent)
- lockdelay (String, range: 1s-60s, default:
15s
): the time consul prevents locks held by the session from being acquired after a session has been invalidated - name (String, optional): human readable name for the session
- node (String, optional): node with which to associate session (defaults to connected agent)
- checks (String[], optional): checks to associate with session
- behavior (String, enum: release, delete; default: release): controls the behavior when a session is invalidated
- ttl (String, optional, valid:
10s
-3600s
): interval session must be renewed
Usage
consul.session.create(function(err, result) {
if (err) throw err;
});
Result
{
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1"
}
Destroy a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.session.destroy('a0f5dc05-84c3-5f5a-1d88-05b875e524e1', function(err) {
if (err) throw err;
});
Queries a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.session.get('a0f5dc05-84c3-5f5a-1d88-05b875e524e1', function(err, result) {
if (err) throw err;
});
Result
{
"CreateIndex": 11,
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"Name": "",
"Node": "node1",
"Checks": [
"serfHealth"
],
"LockDelay": 15000000000
}
Lists sessions belonging to a node.
Options
- node (String): node
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.session.node('node1', function(err, result) {
if (err) throw err;
});
Result
[
{
"CreateIndex": 13,
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"Name": "",
"Node": "node1",
"Checks": [
"serfHealth"
],
"LockDelay": 15000000000
}
]
Lists all the active sessions.
Options
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.session.list(function(err, result) {
if (err) throw err;
});
Result
[
{
"CreateIndex": 15,
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"Name": "",
"Node": "node1",
"Checks": [
"serfHealth"
],
"LockDelay": 15000000000
}
]
Renew a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consul.session.renew('a0f5dc05-84c3-5f5a-1d88-05b875e524e1', function(err, renew) {
if (err) throw err;
});
Result
[
{
"CreateIndex": 15,
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"Name": "",
"Node": "node1",
"Checks": [
"serfHealth"
],
"LockDelay": 15000000000,
"Behavior": "release",
"TTL": ""
}
]
Returns the current Raft leader.
Usage
consul.status.leader(function(err, result) {
if (err) throw err;
});
Result
"127.0.0.1:8300"
Returns the current Raft peer set.
Usage
consul.status.peers(function(err, result) {
if (err) throw err;
});
Result
[
"127.0.0.1:8300"
]
Watch an endpoint for changes.
The watch relies on blocking queries, adding the index
and wait
parameters as per Consul's documentation
If a blocking query is dropped due to a Consul crash or disconnect, watch will attempt to reinitiate the blocking query with logarithmic backoff.
Upon reconnect, unlike the first call to watch() in which the latest x-consul-index
is unknown, the last known x-consul-index
will be reused, thus not emitting the change
event unless it has been incremented since.
Options
- method (Function): method to watch
- options (Object): method options
Usage
var watch = consul.watch({ method: consul.kv.get, options: { key: 'test' }});
watch.on('change', function(data, res) {
console.log('data:', data);
});
watch.on('error', function(err) {
console.log('error:', err);
});
setTimeout(function() { watch.end(); }, 30 * 1000);
var Bluebird = require('bluebird');
function fromCallback(fn) {
return new Bluebird(function(resolve, reject) {
try {
return fn(function(err, data, res) {
if (err) {
err.res = res;
return reject(err);
}
return resolve([data, res]);
});
} catch (err) {
return reject(err);
}
});
}
var consul = require('consul')({ promisify: fromCallback });
consul.kv.set('test', 'hello world').then(function() {
consul.kv.keys().spread(function(data, res) {
console.log('data:', data);
console.log('headers:', res.headers);
});
});
-
Install Consul into your
PATH
$ brew install consul
-
Attach required IPs
$ sudo ifconfig lo0 alias 127.0.0.2 up $ sudo ifconfig lo0 alias 127.0.0.3 up
-
Install client dependencies
$ npm install
-
Run tests
$ npm run acceptance
This work is licensed under the MIT License (see the LICENSE file).
Parts of the Documentation were copied from the official Consul website, see the NOTICE file for license information.