Consul client
npm install @brimble/consul> [!CAUTION]
> This project is no longer maintained.
This is a [Consul][consul] client.
See the official [HTTP API][consul-docs-api] docs for more information.
- Consul
- Common Method Call Options
* ACL
- Legacy
* Agent
- Check
- Service
* Catalog
- Connect
- Node
- Service
* Event
* Health
* Intention
* KV
* Query
* Resolver
* Session
* Status
* Transaction
* Watch
Initialize a new Consul client.
Options
- host (String, default: 127.0.0.1): agent address
- port (Integer, default: 8500): agent HTTP(S) port
- secure (Boolean, default: false): enable HTTPS
- defaults (Object, optional): common method call options that will be included with every call (ex: set default token), these options can be override on a per call basis
Advanced options
- agent (http.Agent|https.Agent, optionals): if not set uses the global agent
- baseUrl, headers, tags, socketPath, and timeout (see Papi for details)
- tls options: ca, cert, ciphers, clientCertEngine, crl, dhparam, ecdhCurve, honorCipherOrder, key, passphrase, pfx, rejectUnauthorized, secureOptions, secureProtocol, servername, and sessionIdContext (see Node.js docs for details)
Usage
``javascript
import Consul from "consul";
const consul = new Consul();
`
These options can be included with any method call, although only certain endpoints support them. See the [HTTP API][consul-docs-api] for more information.
- dc (String, optional): datacenter (defaults to local for agent)
- partition (String, optional): partition (defaults to 'default' partition)
- 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 changes5m
- wait (String, optional): limit how long to wait for changes (ex: ), used with index
- token (String, optional): ACL token
- near (String, optional): used to sort the node list in ascending order based on the estimated round trip time from that node
- node-meta (String[], optional): used to specify a desired node metadata key/value pair of the form key:value
- filter (String, optional): used to refine a data query for some API listing endpoints
These options work for all methods.
- ctx (EventEmitter, optional): emit cancel to abort request1000
- timeout (Number|String, optional): number of milliseconds before request is aborted (ex: or 1s)
- bootstrap
- legacy
- replication
Creates one-time management token if not configured.
Usage
`javascript`
await consul.acl.bootstrap();
Result
`json`
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
Get the status of the ACL replication process in the datacenter.
Usage
`javascript`
await consul.acl.replication();
Result
`json`
{
"Enabled": true,
"Running": true,
"SourceDatacenter": "dc1",
"ReplicatedIndex": 1976,
"LastSuccess": "2016-08-05T06:28:58Z",
"LastError": "2016-08-05T06:28:28Z"
}
- 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
`javascript`
await consul.acl.legacy.create();
Result
`json`
{
"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
`javascript`
await consul.acl.legacy.update({
id: "63e1d82e-f718-eb92-3b7d-61f0c71d45b4",
name: "test",
});
Destroys a given token.
Options
- id (String): token ID
Usage
`javascript`
await consul.acl.legacy.destroy("b1f4c10e-b61b-e1de-de95-218c9fefdd3e");
Queries the policy of a given token.
Options
- id (String): token ID
Usage
`javascript`
await consul.acl.legacy.get("63e1d82e-f718-eb92-3b7d-61f0c71d45b4");
Result
`json`
{
"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
`javascript`
await consul.acl.legacy.clone("63e1d82e-f718-eb92-3b7d-61f0c71d45b4");
Result
`json`
{
"ID": "9fb8b20b-2636-adbb-9b99-d879df3305ec"
}
Lists all the active tokens.
Usage
`javascript`
await consul.acl.legacy.list();
Result
`json`
[
{
"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
- reload
- 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
`javascript`
await consul.agent.members();
Result
`json`
[
{
"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
`javascript`
await consul.agent.reload();
Returns the agent node configuration.
Usage
`javascript`
await consul.agent.self();
Result
`json`
{
"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
`javascript`
await consul.agent.maintenance(true);
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
`javascript`
await consul.agent.join("127.0.0.2");
Force remove node.
Options
- node (String): node name to remove
Usage
`javascript`
await consul.agent.forceLeave("node2");
- list
- register
- deregister
- pass
- warn
- fail
Returns the checks the agent is managing.
Usage
`javascript`
await consul.agent.check.list();
Result
`json`
{
"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
- tlsskipverify (Boolean, default: false): skip HTTPS verification
- tcp (String): host:port to test, passes if connection is established, fails otherwise
- args (String[]): path to check script, requires interval
- script (String): path to check script, requires interval (DEPRECATED)
- dockercontainerid (String, optional): Docker container ID to run script
- grpc (String, optional): gRPC endpoint (ex: 127.0.0.1:12345)15s
- grpcusetls (Boolean, optional): enable TLS for gRPC check
- shell (String, optional): shell in which to run script (currently only supported with Docker)
- interval (String): interval to run check, requires script (ex: )10s
- timeout (String, optional): timeout for the check (ex: )60s
- ttl (String): time to live before check must be updated (ex: )web1
- aliasnode (String): ID of a node for an alias check (ex: )web
- aliasservice (String): ID of a service for an alias check (ex: )
- 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
- successbeforepassing (Number, optional): number of consecutive successful
results required before check status transitions to passing
- failuresbeforecritical (Number, optional): number of consecutive unsuccessful
results required before check status transitions to critical
Usage
`javascript`
await consul.agent.check.register({
name: "example",
ttl: "15s",
notes: "This is an example check.",
});
Deregister a check.
Options
- id (String): check ID
Usage
`javascript`
await consul.agent.check.deregister("example");
Mark a test as passing.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
`javascript`
await consul.agent.check.pass("example");
Mark a test as warning.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
`javascript`
await consul.agent.check.warn("example");
Mark a test as critical.
Options
- id (String): check ID
- note (String, optional): human readable message
Usage
`javascript`
await consul.agent.check.fail("example");
- list
- register
- deregister
- maintenance
Returns the services the agent is managing.
Usage
`javascript`
await consul.agent.service.list();
Result
`json`
{
"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
- meta (Object, optional): metadata linked to the service instance
- 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)10s
- timeout (String, optional): timeout for the check (ex: )60s
- ttl (String): time to live before check must be updated, instead of http/tcp/script and interval (ex: )check
- 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 above)
- connect (Object, optional): specifies the configuration for Connect
- proxy (Object, optional): specifies the configuration for a Connect proxy instance
- taggedAddresses (Object, optional): specifies a map of explicit LAN and WAN addresses for the service instance
Usage
`javascript`
await consul.agent.service.register("example");
Deregister a service.
Options
- id (String): service ID
Usage
`javascript`
await consul.agent.service.deregister("example");
Set service maintenance mode.
Options
- id (String): service ID
- enable (Boolean): maintenance mode enabled
- reason (String, optional): human readable reason for maintenance
Usage
`javascript`
await consul.agent.service.maintenance({ id: "example", enable: true });
- register
- deregister
- datacenters
- connect
- node
- service
Registers or updates entries in the catalog.
NOTE: this endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the agent endpoints for registration as they are simpler and perform anti-entropy. It is suggested to read the catalog API documentation before using that.
Options
- id (String, optional): an optional UUID to assign to the node. This must be a 36-character UUID-formatted string
- node (String, required): specifies the node ID to register
- address (String, required): specifies the address to register.
- taggedaddresses (Object, optional): specifies the tagged addresses
- nodemeta (Object, optional): specifies arbitrary KV metadata pairs for filtering purposes
- service (Objet, optional): specifies to register a service
- id (String): service ID. If ID is not provided, it will be defaulted to the value of the Service.Service property.
Only one service with a given ID may be present per node.
- service (String): service name
- tags (String[], optional): service tags
- meta (Object, optional): metadata linked to the service instance
- address (String): service IP address
- port (Integer): service port
- check (Object, optional): specifies to register a check.The register API manipulates the health check entry in the Catalog, but it does not setup the
TCP/HTTP check to monitor the node's health.
- node (String): the node id this check will bind to
- name (String): check name
- checkid (String): the CheckID can be omitted and will default to the value of Name. The CheckID must be unique on this node.
- serviceid (String): if a ServiceID is provided that matches the ID of a service on that node, the check is treated as a service level health check, instead of a node level health check.
- notes (String): notes is an opaque field that is meant to hold human-readable text
- status (String): initial status. The Status must be one of passing, warning, or critical.15s
- definition (Object): health check definition
- http (String): URL endpoint, requires interval
- tlsskipverify (Boolean, default: false): skip HTTPS verification
- tlsservername (String): SNI
- tcp (String): host:port to test, passes if connection is established, fails otherwise
- intervalduration (String): interval to run check, requires script (ex: )10s
- timeoutduration (String): timeout for the check (ex: )120s
- deregistercriticalserviceafterduration (String): timeout after
which to automatically deregister service if check remains in critical state (ex: )check
- checks (Object[], optional): multiple checks can be provided by replacing with checks and sending an array of check objects.
- skipnodeupdate (Bool, optional): pecifies whether to skip updating the node's information in the registration. Note, if the parameter is enabled for a node that doesn't exist, it will still be created
Usage
`javascript`
await consul.catalog.register("example");
Deregister entries in the catalog.
NOTE:This endpoint is a low-level mechanism for directly removing entries from the Catalog. It is usually preferable to instead use the agent endpoints for deregistration as they are simpler and perform anti-entropy. It is suggested to read the catalog API documentation before using that.
Options
- node (String, required): specifies the ID of the node. If no other values are provided, this node, all its services, and all its checks are removed.
- checkid (String, optional): specifies the ID of the check to remove.
- serviceid (String, optional): specifies the ID of the service to remove. The service and all associated checks will be removed.
Usage
`javascript`
await consul.catalog.deregister("example");
or
`javascript`
await consul.catalog.deregister({ id: "example" });
Lists known datacenters.
Usage
`javascript`
await consul.catalog.datacenters();
Result
`json`
["dc1"]
- nodes
Lists the nodes for a given Connect-capable service.
Options
- service (String): service name
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.catalog.connect.nodes("example");
Result
`json`
[
{
"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
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.catalog.node.list();
Result
`json`
[
{
"Node": "node1",
"Address": "127.0.0.1"
}
]
Lists the services provided by a node.
Options
- node (String): node ID
Usage
`javascript`
await consul.catalog.node.services("node1");
Result
`json`
{
"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
`javascript`
await consul.catalog.service.list();
Result
`json`
{
"consul": [],
"example": ["dev", "web"]
}
Lists the nodes for a given service.
Options
- service (String): service name
- dc (String, optional): datacenter (defaults to local for agent)
- tag (String, optional): filter by tag
Usage
`javascript`
await consul.catalog.service.nodes("example");
Result
`json`
[
{
"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
`javascript`
await consul.event.fire("deploy", "53");
Result
`json`
{
"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
`javascript`
await consul.event.list("deploy");
Result
`json`
[
{
"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
`javascript`
await consul.health.node("node1");
Result
`json`
[
{
"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
`javascript`
await consul.health.checks("example");
Result
`json`
[
{
"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
`javascript`
await consul.health.service("example");
Result
`json`
[
{
"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
`javascript`
await consul.health.state("critical");
Result
`json`
[
{
"Node": "node1",
"CheckID": "service:example",
"Name": "Service 'example' check",
"Status": "critical",
"Notes": "",
"Output": "",
"ServiceID": "example",
"ServiceName": "example"
}
]
- list
- create
- get
- update
- destroy
List all Connect intentions.
Options
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.intention.list();
Result
`json`
[
{
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"SourceName": "web",
"DestinationName": "db",
"SourceType": "",
"Action": "allow",
"Description": "",
"Meta": null,
"Precedence": 9,
"CreateIndex": 11,
"ModifyIndex": 12
}
]
Create a new Connect intention.
Options
- sourcename (String, required): source service name
- destinationname (String, required): destination service name
- action (String, enum: allow, deny; required): action to take
- description (String, optional): human readable description
- sourcetype (String, optional): source type (e.g., "consul")
- meta (Object, optional): metadata key/value pairs
- precedence (Number, optional): precedence for the intention
- permissions (Array, optional): L7 permissions for application-aware intentions
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.intention.create({
sourcename: "web",
destinationname: "db",
action: "allow",
description: "Allow web service to access database",
});
Result
`json`
{
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1"
}
Get a specific Connect intention.
Options
- id (String, required): intention ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.intention.get("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
Result
`json`
{
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"SourceName": "web",
"DestinationName": "db",
"SourceType": "",
"Action": "allow",
"Description": "Allow web service to access database",
"Meta": null,
"Precedence": 9,
"CreateIndex": 11,
"ModifyIndex": 12
}
Update an existing Connect intention.
Options
- id (String, required): intention ID
- sourcename (String, required): source service name
- destinationname (String, required): destination service name
- action (String, enum: allow, deny; required): action to take
- description (String, optional): human readable description
- sourcetype (String, optional): source type (e.g., "consul")
- meta (Object, optional): metadata key/value pairs
- precedence (Number, optional): precedence for the intention
- permissions (Array, optional): L7 permissions for application-aware intentions
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.intention.update({
id: "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
sourcename: "web",
destinationname: "db",
action: "deny",
description: "Block web service from accessing database",
});
Delete a Connect intention.
Options
- id (String, required): intention ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.intention.destroy("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
Create a DNS resolver instance for load balancing and service discovery with Consul.
The resolver provides intelligent service selection using multiple algorithms, DNS resolution, health checks, and Redis-based metrics tracking.
Options
- redis (Redis, optional): ioredis instance for caching (required if cacheEnabled is true)
- cacheEnabled (Boolean, default: false): enable Redis caching
- cachePrefix (String, required): prefix for Redis cache keys
- debug (Boolean, default: false): enable debug logging
- weights (Object, optional): custom weights for weighted round robin algorithm
- health (Number, default: 0.25): weight for health score
- responseTime (Number, default: 0.2): weight for response time
- errorRate (Number, default: 0.2): weight for error rate
- resources (Number, default: 0.15): weight for CPU/memory usage
- connections (Number, default: 0.1): weight for active connections
- distribution (Number, default: 0.1): weight for distribution fairness
- metrics (Object, optional): default metrics for new services
- responseTime (Number, default: 100): default response time in ms
- errorRate (Number, default: 0): default error rate percentage
- cpuUsage (Number, default: 50): default CPU usage percentage
- memoryUsage (Number, default: 50): default memory usage percentage
- activeConnections (Number, default: 0): default active connections
- cacheTTL (Number, default: 60000): cache TTL in milliseconds
- dnsEndpoints (String[], optional): custom DNS endpoints
- dnsTimeout (Number, default: 1500): DNS query timeout in milliseconds
- dnsRetries (Number, default: 2): number of DNS retry attempts
Usage
`javascript
import Consul from "@brimble/consul";
import Redis from "ioredis";
const consul = new Consul({
host: "127.0.0.1",
port: 8500,
});
const redis = new Redis({
host: "localhost",
port: 6379,
});
const resolver = consul.resolver({
redis,
cacheEnabled: true,
cachePrefix: "myapp",
debug: false,
});
`
Select the optimal service instance based on the specified algorithm.
Options
- service (String, required): service name to resolve
- algorithm (String, optional): selection algorithm
- SelectionAlgorithm.RoundRobin (default): round-robin selectionSelectionAlgorithm.LeastConnection
- : select service with fewest connectionsSelectionAlgorithm.WeightedRoundRobin
- : weighted selection based on metrics
Usage
`javascript
const Consul = require("@brimble/consul");
const { SelectionAlgorithm } = Consul.Resolver;
const result = await resolver.selectOptimalService(
"my-service",
SelectionAlgorithm.LeastConnection,
);
if (result.selected) {
console.log(Selected: ${result.selected.ip}:${result.selected.port});`
}
Result
`json`
{
"selected": {
"ip": "192.168.1.10",
"port": 8080
},
"services": [
{
"ip": "192.168.1.10",
"port": 8080
},
{
"ip": "192.168.1.11",
"port": 8080
}
]
}
Increment the active connection count for a service.
Options
- serviceId (String, required): service ID
Usage
`javascript`
await resolver.incrementConnections("service-id-123");
Decrement the active connection count for a service.
Options
- serviceId (String, required): service ID
Usage
`javascript`
await resolver.decrementConnections("service-id-123");
Get current metrics for a specific service.
Options
- serviceId (String, required): service ID
Usage
`javascript`
const metrics = await resolver.getSelectionMetrics("service-id-123");
Result
`json`
{
"responseTime": 150,
"errorRate": 0.5,
"cpuUsage": 45,
"memoryUsage": 60,
"activeConnections": 10,
"lastSelectedTime": 1234567890
}
Clear all stored metrics from Redis cache.
Usage
`javascript`
await resolver.refresh();
Return key/value (kv) pair(s) or undefined if key not found.
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 changes5m
- wait (String, optional): limit how long to wait for changes (ex: ), 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
`javascript`
await consul.kv.get("hello");
Result
`json`
{
"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
`javascript`
await consul.kv.keys("a/");
Result
`json`
["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
`javascript`
await consul.kv.set("hello", "world");
Result
`json`
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
`javascript`
await consul.kv.del("hello");
- list
- create
- update
- get
- destroy
- execute
- explain
List prepared query.
Usage
`javascript`
await consul.query.list();
Result
`json`
[
{
"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
`javascript`
await consul.query.create({
name: 'redis',
service: {
service: 'redis'
onlypassing: true
},
});
Result
`json`
{
"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
`javascript`
await consul.query.update({
query: '422b14b9-874b-4520-bd2e-e149a42b0066',
name: 'redis',
service: {
service: 'redis'
onlypassing: false
},
});
Get prepared query.
Options
- query (String, required): ID of the query
Usage
`javascript`
await consul.query.get("6119cabf-c052-48fe-9f07-711762e52931");
Result
`json`
{
"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
`javascript`
await consul.query.destroy("422b14b9-874b-4520-bd2e-e149a42b0066");
Execute prepared query.
Options
- query (String, required): ID of the query
Usage
`javascript`
await consul.query.execute("6119cabf-c052-48fe-9f07-711762e52931");
Result
`json`
{
"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
`javascript`
await consul.query.explain("422b14b9-874b-4520-bd2e-e149a42b0066");
Result
`json`
{
"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
- 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 invalidated10s
- 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: -86400s): interval session must be renewed
Usage
`javascript`
await consul.session.create();
Result
`json`
{
"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
`javascript`
await consul.session.destroy("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
Queries a given session.
Options
- id (String): session ID
- dc (String, optional): datacenter (defaults to local for agent)
Usage
`javascript`
await consul.session.get("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
Result
`json`
{
"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
`javascript`
await consul.session.node("node1");
Result
`json`
[
{
"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
`javascript`
await consul.session.list();
Result
`json`
[
{
"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
`javascript`
await consul.session.renew("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");
Result
`json`
[
{
"CreateIndex": 15,
"ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
"Name": "",
"Node": "node1",
"Checks": ["serfHealth"],
"LockDelay": 15000000000,
"Behavior": "release",
"TTL": ""
}
]
Returns the current Raft leader.
Usage
`javascript`
await consul.status.leader();
Result
`json`
"127.0.0.1:8300"
Returns the current Raft peer set.
Usage
`javascript`
await consul.status.peers();
Result
`json`
["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
`javascript`
await 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
- method (Function): method to watch
- options (Object): method options
- backoffFactor (Integer, default: 100): backoff factor in milliseconds to apply between attempts (backoffFactor * (2 ^ retry attempt))
- backoffMax (Integer, default: 30000): maximum backoff time in milliseconds to wait between attempts
- maxAttempts (Integer): maximum number of retry attempts to make before giving up
Usage
`javascript
const watch = consul.watch({
method: consul.kv.get,
options: { key: "test" },
backoffFactor: 1000,
});
watch.on("change", (data, res) => {
console.log("data:", data);
});
watch.on("error", (err) => {
console.log("error:", err);
});
setTimeout(() => {
watch.end();
}, 30 * 1000);
`
1. Install [Consul][download] into your PATH
`console`
$ brew install consul
1. Attach required IPs
`console`
$ sudo ifconfig lo0 alias 127.0.0.2 up
$ sudo ifconfig lo0 alias 127.0.0.3 up
1. Install client dependencies
`console`
$ npm install
1. Run tests
`console``
$ 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][consul-docs-api], see the NOTICE file for license
information.
[consul]: https://www.consul.io/
[consul-docs-api]: https://www.consul.io/api-docs
[download]: https://www.consul.io/downloads