Consul

This is a Consul client.

• Documentation
• Development
• License

Documentation

See the official HTTP API docs for more information.

• Consul
• ACL
• Agent
• Check
• Service
• Catalog
• Node
• Service
• Event
• Health
• KV
• Session
• Status
• Watch

All callbacks 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 when err is set. The body property can be a decoded object, string, or Buffer.

These options will be passed along with any 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 endpoints.

• ctx (EventEmitter, optional): emit cancel to abort request
• timeout (Number, optional): number of milliseconds before request is aborted

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

Usage

var consul = require('consul')();

• create
• update
• destroy
• get
• clone
• list

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": ""
  }
]

• check
• service
• members
• self
• maintenance
• join
• forceLeave

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;
});

• list
• register
• deregister
• pass
• warn
• fail

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
• script (String): path to check script, requires interval
• internal (String): interval to run check, requires script (ex: 15s)
• ttl (String): time to live before check must be updated, instead of script and interval (ex: 60s)
• notes (String, optional): human readable description of check

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

Usage

consul.agent.check.pass('example', function(err) {
  if (err) throw err;
});

Mark a test as warning.

Options

• id (String): check ID

Usage

consul.agent.check.warn('example', function(err) {
  if (err) throw err;
});

Mark a test as critical.

Options

• id (String): check ID

Usage

consul.agent.check.fail('example', function(err) {
  if (err) throw err;
});

• list
• register
• deregister
• maintenance

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
• check (Object, optional): service check
• script (String): path to check script, requires interval
• internal (String): interval to run check, requires script (ex: 15s)
• ttl (String): time to live before check must be updated, instead of script and interval (ex: 60s)
• notes (String, optional): human readable description of check

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;
});

• node
• service
• datacenters

Lists known datacenters.

Usage

consul.catalog.datacenters(function(err, result) {
  if (err) throw err;
});

Result

[
  "dc1"
]

• list
• services

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
    }
  }
}

• list
• nodes

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 ID
• 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
  }
]

• fire
• list

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
  }
]

• node
• checks
• service
• state

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 ID
• 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 ID
• 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"
  }
]

• get
• keys
• set
• del

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 than 0)

Usage

consul.kv.del('hello', function(err) {
  if (err) throw err;
});

• create
• destroy
• get
• node
• list
• renew

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": ""
  }
]

• leader
• peers

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.

Options

• fn (Function): method to watch
• opts (Object): method options
• callback (Function, optional): change/error callback

Usage

var watch = consul.watch(consul.kv.get, { 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);

Development

1. Install Consul into your PATH.

2. Attach required IPs

   $ sudo ifconfig lo0 alias 127.0.0.2 up
   $ sudo ifconfig lo0 alias 127.0.0.3 up

3. Install client dependencies

   $ npm install

4. Run tests

   $ npm test

License

This work is licensed under the MIT License (see the LICENSE file).