This is a Consul client.
See the official HTTP API docs for more information.
Initialize a new Consul client.
Options
token), these options can be override on a per call basisUsage
var consul = require('consul')();
All callback methods have the following signature function(err, data, res).
undefinedbody property. This might not exist when err is set. The body 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 can be included with any method call, although only certain endpoints support them. See the HTTP API for more information.
ModifyIndex to block and wait for changes5m), used with indexThese options work for all methods.
cancel to abort request1000 or 1s)Creates one-time management token if not configured.
Usage
consul.acl.bootstrap(function(err, result) {
if (err) throw err;
});
Result
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
Creates a new token with policy.
Options
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
Usage
consul.acl.update({ id: '63e1d82e-f718-eb92-3b7d-61f0c71d45b4', name: 'test' }, function(err) {
if (err) throw err;
});
Destroys a given token.
Options
Usage
consul.acl.destroy('b1f4c10e-b61b-e1de-de95-218c9fefdd3e', function(err) {
if (err) throw err;
});
Queries the policy of a given token.
Options
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
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": ""
}
]
Get the status of the ACL replication process in the datacenter.
Usage
consul.acl.replication(function(err, result) {
if (err) throw err;
});
Result
{
"Enabled": true,
"Running": true,
"SourceDatacenter": "dc1",
"ReplicatedIndex": 1976,
"LastSuccess": "2016-08-05T06:28:58Z",
"LastError": "2016-08-05T06:28:28Z"
}
Returns the members as seen by the consul agent.
Options
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
}
]
Reload agent configuration.
Usage
consul.agent.reload(function(err, result) {
if (err) throw err;
});
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
Usage
consul.agent.maintenance(true, function(err) {
if (err) throw err;
});
Trigger agent to join a node.
Options
Usage
consul.agent.join('127.0.0.2', function(err) {
if (err) throw err;
});
Force remove node.
Options
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
127.0.0.1:12345)15s)10s)60s)web1)web)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
Usage
consul.agent.check.deregister('example', function(err) {
if (err) throw err;
});
Mark a test as passing.
Options
Usage
consul.agent.check.pass('example', function(err) {
if (err) throw err;
});
Mark a test as warning.
Options
Usage
consul.agent.check.warn('example', function(err) {
if (err) throw err;
});
Mark a test as critical.
Options
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
15s)10s)60s)check above)Usage
consul.agent.service.register('example', function(err) {
if (err) throw err;
});
Deregister a service.
Options
Usage
consul.agent.service.deregister('example', function(err) {
if (err) throw err;
});
Set service maintenance mode.
Options
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 the nodes for a given Connect-capable service.
Options
Usage
consul.catalog.connect.nodes('example', function(err, result) {
if (err) throw err;
});
Result
[
{
"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
"Node": "foobar",
"Address": "192.168.10.10",
"Datacenter": "dc1",
"TaggedAddresses": {
"lan": "192.168.10.10",
"wan": "10.0.10.10"
},
"NodeMeta": {
"somekey": "somevalue"
},
"CreateIndex": 51,
"ModifyIndex": 51,
"ServiceAddress": "172.17.0.3",
"ServiceEnableTagOverride": false,
"ServiceID": "32a2a47f7992:nodea:5000",
"ServiceName": "foobar",
"ServiceKind": "connect-proxy",
"ServiceProxyDestination": "my-service",
"ServicePort": 5000,
"ServiceMeta": {
"foobar_meta_value": "baz"
},
"ServiceTags": [
"tacos"
]
}
]
Lists nodes in a given datacenter.
Options
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
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
Usage
consul.catalog.service.list(function(err, result) {
if (err) throw err;
});
Result
{
"consul": [],
"example": [
"dev",
"web"
]
}
Lists the nodes for a given service.
Options
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
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
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
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
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
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
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) or undefined if key not found.
Options
ModifyIndex to block and wait for changes5m), used with indexUsage
consul.kv.get('hello', function(err, result) {
if (err) throw err;
if (result === undefined) throw new Error('key not found');
});
Result
{
"CreateIndex": 6,
"ModifyIndex": 6,
"LockIndex": 0,
"Key": "hello",
"Flags": 0,
"Value": "world"
}
Return keys for a given prefix.
Options
Usage
consul.kv.keys('a/', function(err, result) {
if (err) throw err;
});
Result
[
"a/b",
"a/c"
]
Set key/value (kv) pair.
Options
ModifyIndex to do a check-and-set operationUsage
consul.kv.set('hello', 'world', function(err, result) {
if (err) throw err;
});
Result
true
Delete key/value (kv) pair(s).
Options
ModifyIndex to do a check-and-set operation (must be greater than 0)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
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
10s): controls how the TTL is set when query results are served over DNSUsage
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
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
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
Usage
consul.query.destroy('422b14b9-874b-4520-bd2e-e149a42b0066', function(err) {
if (err) throw err;
});
Execute prepared query.
Options
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
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
15s): the time consul prevents locks held by the session from being acquired after a session has been invalidated10s-86400s): interval session must be renewedUsage
consul.session.create(function(err, result) {
if (err) throw err;
});
Result
{
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1"
}
Destroy a given session.
Options
Usage
consul.session.destroy('a0f5dc05-84c3-5f5a-1d88-05b875e524e1', function(err) {
if (err) throw err;
});
Queries a given session.
Options
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
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
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
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"
]
operations: The body of the request should be a list of operations to perform inside the atomic transaction. Up to 64 operations may be present in a single transaction.
Usage
consul.transaction.create([
{
{
KV: {
Verb: 'set',
Key: 'key1',
Value: Buffer.from('value1').toString('base64')
}
},{
KV: {
Verb: 'delete',
Key: 'key2'
}
}
}
]);
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.
NOTE: If you specify an alternative options.timeout keep in mind that a small random amount of additional wait is added to all requests (wait / 16). The default timeout is currently set to (wait + wait * 0.1), you should use something similar to avoid issues.
Options
backoffFactor * (2 ^ retry attempt))Usage
var watch = consul.watch({
method: consul.kv.get,
options: { key: 'test' },
backoffFactor: 1000,
});
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.
FAQs
Consul client
We found that consul demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.