Consul
This is a Consul client.
Documentation
See the official HTTP API docs for more information.
### CallbackAll 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 whenerr
is set. Thebody
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
### consul.acl ### consul.acl.create([options], callback)var consul = ;
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
consulacl;
Result
### consul.acl.update(options, callback)
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.destroy(options, callback)consulacl;
Destroys a given token.
Options
- id (String): token ID
Usage
### consul.acl.get(options, callback)consulacl;
Queries the policy of a given token.
Options
- id (String): token ID
Usage
consulacl;
Result
### consul.acl.clone(options, callback)
Creates a new token by cloning an existing token.
Options
- id (String): token ID
Usage
consulacl;
Result
### consul.acl.list([options], callback)
Lists all the active tokens.
Usage
consulacl;
Result
### consul.agent ### consul.agent.members([options], callback)
Returns the members as seen by the consul agent.
Options
- wan (Boolean, default: false): return WAN members instead of LAN members
Usage
consulagent;
Result
### consul.agent.self(callback)
Returns the agent node configuration.
Usage
consulagentself {if err throw err;};
Result
### consul.agent.maintenance(options, callback)
Set node maintenance mode.
Options
- enable (Boolean): maintenance mode enabled
- reason (String, optional): human readable reason for maintenance
Usage
### consul.agent.join(options, callback)consulagent;
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.forceLeave(options, callback)consulagent;
Force remove node.
Options
- node (String): node name to remove
Usage
### consul.agent.check ### consul.agent.check.list(callback)consulagent;
Returns the checks the agent is managing.
Usage
consulagentcheck;
Result
### consul.agent.check.register(options, callback)
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
### consul.agent.check.deregister(options, callback)var check =name: 'example'ttl: '15s'notes: 'This is an example check.';consulagentcheck;
Deregister a check.
Options
- id (String): check ID
Usage
### consul.agent.check.pass(options, callback)consulagentcheck;
Mark a test as passing.
Options
- id (String): check ID
Usage
### consul.agent.check.warn(options, callback)consulagentcheck;
Mark a test as warning.
Options
- id (String): check ID
Usage
### consul.agent.check.fail(options, callback)consulagentcheck;
Mark a test as critical.
Options
- id (String): check ID
Usage
### consul.agent.service ### consul.agent.service.list(callback)consulagentcheck;
Returns the services the agent is managing.
Usage
consulagentservice;
Result
### consul.agent.service.register(options, callback)
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.deregister(options, callback)consulagentservice;
Deregister a service.
Options
- id (String): service ID
Usage
### consul.agent.service.maintenance(options, callback)consulagentservice;
Set service maintenance mode.
Options
- id (String): service ID
- enable (Boolean): maintenance mode enabled
- reason (String, optional): human readable reason for maintenance
Usage
### consul.catalog ### consul.catalog.datacenters(callback)consulagentservice;
Lists known datacenters.
Usage
consulcatalog;
Result
### consul.catalog.node ### consul.catalog.node.list([options], callback)
Lists nodes in a given datacenter.
Options
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulcatalognode;
Result
### consul.catalog.node.services(options, callback)
Lists the services provided by a node.
Options
- node (String): node ID
Usage
consulcatalognode;
Result
### consul.catalog.service ### consul.catalog.service.list([options], callback)
Lists services in a given datacenter.
Options
- dc (String): datacenter (defaults to local for agent)
Usage
consulcatalogservice;
Result
### consul.catalog.service.nodes(options, callback)
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
consulcatalogservice;
Result
### consul.event ### consul.event.fire(options, callback)
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
consulevent;
Result
### consul.event.list([options], callback)
Lists the most recent events an agent has seen.
Options
- name (String, optional): filter by event name
Usage
consulevent;
Result
### consul.health ### consul.health.node(options, callback)
Returns the health info of a node.
Options
- node (String): node
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulhealth;
Result
### consul.health.checks(options, callback)
Returns the checks of a service.
Options
- service (String): service ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulhealth;
Result
### consul.health.service(options, callback)
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
consulhealth;
Result
### consul.health.state(options, callback)
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
consulhealth;
Result
### consul.kv ### consul.kv.get(options, callback)
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
consulkv;
Result
### consul.kv.keys(options, callback)
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
consulkv;
Result
### consul.kv.set(options, callback)
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
consulkv;
Result
### consul.kv.del(options, callback)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.session ### consul.session.create([options], callback)consulkv;
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
consulsession;
Result
### consul.session.destroy(options, callback)
Destroy a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
### consul.session.get(options, callback)consulsession;
Queries a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulsession;
Result
### consul.session.node(options, callback)
Lists sessions belonging to a node.
Options
- node (String): node
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulsession;
Result
### consul.session.list([options], callback)
Lists all the active sessions.
Options
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulsession;
Result
### consul.session.renew(options, callback)
Renew a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
consulsession;
Result
### consul.status ### consul.status.leader(callback)
Returns the current Raft leader.
Usage
consulstatus;
Result
### consul.status.peers(callback)"127.0.0.1:8300"
Returns the current Raft peer set.
Usage
consulstatus;
Result
### consul.watch(fn, opts, [callback])
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;watch;;
Development
-
Install Consul into your
PATH
. -
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 test
License
This work is licensed under the MIT License (see the LICENSE file).