consul

v2.0.1

Published

2 months ago

Consul client

Downloads

372,147

0High
0Medium
0Low

silas

consul

Consul

This is a Consul client.

Documentation

See the official HTTP API docs for more information.

Consul
- Common Method Call Options

Consul([options])

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

import Consul from "consul";

const consul = new Consul();

Common Method Call Options

These options can be included with any method call, although only certain endpoints support them. See the HTTP API for more information.

dc (String, optional): datacenter (defaults to local for agent)
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 changes
wait (String, optional): limit how long to wait for changes (ex: 5m), 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 request
timeout (Number|String, optional): number of milliseconds before request is aborted (ex: 1000 or 1s)

consul.acl

consul.acl.bootstrap()

Creates one-time management token if not configured.

Usage

await consul.acl.bootstrap();

Result

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

consul.acl.replication([options])

Get the status of the ACL replication process in the datacenter.

Usage

await consul.acl.replication();

Result

{
  "Enabled": true,
  "Running": true,
  "SourceDatacenter": "dc1",
  "ReplicatedIndex": 1976,
  "LastSuccess": "2016-08-05T06:28:58Z",
  "LastError": "2016-08-05T06:28:28Z"
}

consul.acl.legacy

consul.acl.legacy.create([options])

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

await consul.acl.legacy.create();

Result

{
  "ID": "b1f4c10e-b61b-e1de-de95-218c9fefdd3e"
}

consul.acl.legacy.update(options)

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

await consul.acl.legacy.update({
  id: "63e1d82e-f718-eb92-3b7d-61f0c71d45b4",
  name: "test",
});

consul.acl.legacy.destroy(options)

Destroys a given token.

Options

id (String): token ID

Usage

await consul.acl.legacy.destroy("b1f4c10e-b61b-e1de-de95-218c9fefdd3e");

consul.acl.legacy.get(options)

Queries the policy of a given token.

Options

id (String): token ID

Usage

await consul.acl.legacy.get("63e1d82e-f718-eb92-3b7d-61f0c71d45b4");

Result

{
  "CreateIndex": 7,
  "ModifyIndex": 7,
  "ID": "63e1d82e-f718-eb92-3b7d-61f0c71d45b4",
  "Name": "Read only",
  "Type": "client",
  "Rules": "{\"key\":{\"\":{\"policy\":\"read\"}}}"
}

consul.acl.legacy.clone(options)

Creates a new token by cloning an existing token.

Options

id (String): token ID

Usage

await consul.acl.legacy.clone("63e1d82e-f718-eb92-3b7d-61f0c71d45b4");

Result

{
  "ID": "9fb8b20b-2636-adbb-9b99-d879df3305ec"
}

consul.acl.legacy.list([options])

Lists all the active tokens.

Usage

await consul.acl.legacy.list();

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

consul.agent

consul.agent.members([options])

Returns the members as seen by the consul agent.

Options

wan (Boolean, default: false): return WAN members instead of LAN members

Usage

await consul.agent.members();

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

consul.agent.reload([options])

Reload agent configuration.

Usage

await consul.agent.reload();

consul.agent.self()

Returns the agent node configuration.

Usage

await consul.agent.self();

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

consul.agent.maintenance(options)

Set node maintenance mode.

Options

enable (Boolean): maintenance mode enabled
reason (String, optional): human readable reason for maintenance

Usage

await consul.agent.maintenance(true);

consul.agent.join(options)

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

await consul.agent.join("127.0.0.2");

consul.agent.forceLeave(options)

Force remove node.

Options

node (String): node name to remove

Usage

await consul.agent.forceLeave("node2");

consul.agent.check

consul.agent.check.list()

Returns the checks the agent is managing.

Usage

await consul.agent.check.list();

Result

{
  "example": {
    "Node": "node1",
    "CheckID": "example",
    "Name": "example",
    "Status": "passing",
    "Notes": "This is an example check.",
    "Output": "",
    "ServiceID": "",
    "ServiceName": ""
  }
}

consul.agent.check.register(options)

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)
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: 15s)
timeout (String, optional): timeout for the check (ex: 10s)
ttl (String): time to live before check must be updated (ex: 60s)
aliasnode (String): ID of a node for an alias check (ex: web1)
aliasservice (String): ID of a service for an alias check (ex: web)
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

await consul.agent.check.register({
  name: "example",
  ttl: "15s",
  notes: "This is an example check.",
});

consul.agent.check.deregister(options)

Deregister a check.

Options

id (String): check ID

Usage

await consul.agent.check.deregister("example");

consul.agent.check.pass(options)

Mark a test as passing.

Options

id (String): check ID
note (String, optional): human readable message

Usage

await consul.agent.check.pass("example");

consul.agent.check.warn(options)

Mark a test as warning.

Options

id (String): check ID
note (String, optional): human readable message

Usage

await consul.agent.check.warn("example");

consul.agent.check.fail(options)

Mark a test as critical.

Options

id (String): check ID
note (String, optional): human readable message

Usage

await consul.agent.check.fail("example");

consul.agent.service

consul.agent.service.list()

Returns the services the agent is managing.

Usage

await consul.agent.service.list();

Result

{
  "example": {
    "ID": "example",
    "Service": "example",
    "Tags": ["dev", "web"],
    "Port": 80
  }
}

consul.agent.service.register(options)

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)
- timeout (String, optional): timeout for the check (ex: 10s)
- ttl (String): time to live before check must be updated, instead of http/tcp/script and interval (ex: 60s)
- notes (String, optional): human readable description of check
- status (String, optional): initial service status
- deregistercriticalserviceafter (String, optional, Consul 0.7+): timeout after which to automatically deregister service if check remains in critical state
checks (Object[], optional): service checks (see check above)
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

await consul.agent.service.register("example");

consul.agent.service.deregister(options)

Deregister a service.

Options

id (String): service ID

Usage

await consul.agent.service.deregister("example");

consul.agent.service.maintenance(options)

Set service maintenance mode.

Options

id (String): service ID
enable (Boolean): maintenance mode enabled
reason (String, optional): human readable reason for maintenance

Usage

await consul.agent.service.maintenance({ id: "example", enable: true });

consul.catalog

consul.catalog.register(options)

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.
- 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: 15s)
  - timeoutduration (String): timeout for the check (ex: 10s)
  - deregistercriticalserviceafterduration (String): timeout after which to automatically deregister service if check remains in critical state (ex: 120s)
checks (Object[], optional): multiple checks can be provided by replacing check 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

await consul.catalog.register("example");

consul.catalog.deregister(options)

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

await consul.catalog.deregister("example");

await consul.catalog.deregister({ id: "example" });

consul.catalog.datacenters()

Lists known datacenters.

Usage

await consul.catalog.datacenters();

Result

["dc1"]

consul.catalog.connect

nodes

consul.catalog.connect.nodes(options)

Lists the nodes for a given Connect-capable service.

Options

service (String): service name
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.catalog.connect.nodes("example");

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

consul.catalog.node

consul.catalog.node.list([options])

Lists nodes in a given datacenter.

Options

dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.catalog.node.list();

Result

[
  {
    "Node": "node1",
    "Address": "127.0.0.1"
  }
]

consul.catalog.node.services(options)

Lists the services provided by a node.

Options

node (String): node ID

Usage

await consul.catalog.node.services("node1");

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

consul.catalog.service

consul.catalog.service.list([options])

Lists services in a given datacenter.

Options

dc (String): datacenter (defaults to local for agent)

Usage

await consul.catalog.service.list();

Result

{
  "consul": [],
  "example": ["dev", "web"]
}

consul.catalog.service.nodes(options)

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

await consul.catalog.service.nodes("example");

Result

[
  {
    "Node": "node1",
    "Address": "127.0.0.1",
    "ServiceID": "example",
    "ServiceName": "example",
    "ServiceTags": ["dev", "web"],
    "ServicePort": 80
  }
]

consul.event

consul.event.fire(options)

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

await consul.event.fire("deploy", "53");

Result

{
  "ID": "4730953b-3135-7ff2-47a7-9d9fc9c4e5a2",
  "Name": "deploy",
  "Payload": "53",
  "NodeFilter": "",
  "ServiceFilter": "",
  "TagFilter": "",
  "Version": 1,
  "LTime": 0
}

consul.event.list([options])

Lists the most recent events an agent has seen.

Options

name (String, optional): filter by event name

Usage

await consul.event.list("deploy");

Result

[
  {
    "ID": "4730953b-3135-7ff2-47a7-9d9fc9c4e5a2",
    "Name": "deploy",
    "Payload": "53",
    "NodeFilter": "",
    "ServiceFilter": "",
    "TagFilter": "",
    "Version": 1,
    "LTime": 2
  }
]

consul.health

consul.health.node(options)

Returns the health info of a node.

Options

node (String): node
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.health.node("node1");

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

consul.health.checks(options)

Returns the checks of a service.

Options

service (String): service name
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.health.checks("example");

Result

[
  {
    "Node": "node1",
    "CheckID": "service:example",
    "Name": "Service 'example' check",
    "Status": "critical",
    "Notes": "",
    "Output": "",
    "ServiceID": "example",
    "ServiceName": "example"
  }
]

consul.health.service(options)

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

await consul.health.service("example");

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

consul.health.state(options)

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

await consul.health.state("critical");

Result

[
  {
    "Node": "node1",
    "CheckID": "service:example",
    "Name": "Service 'example' check",
    "Status": "critical",
    "Notes": "",
    "Output": "",
    "ServiceID": "example",
    "ServiceName": "example"
  }
]

consul.kv

consul.kv.get(options)

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

await consul.kv.get("hello");

Result

{
  "CreateIndex": 6,
  "ModifyIndex": 6,
  "LockIndex": 0,
  "Key": "hello",
  "Flags": 0,
  "Value": "world"
}

consul.kv.keys(options)

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

await consul.kv.keys("a/");

Result

["a/b", "a/c"]

consul.kv.set(options)

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

await consul.kv.set("hello", "world");

Result

true

consul.kv.del(options)

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

await consul.kv.del("hello");

consul.query

consul.query.list()

List prepared query.

Usage

await consul.query.list();

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

consul.query.create(options)

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

await consul.query.create({
  name: 'redis',
  service: {
    service: 'redis'
    onlypassing: true
  },
});

Result

{
  "ID": "422b14b9-874b-4520-bd2e-e149a42b0066"
}

consul.query.update(options)

Update existing prepared query.

Options

query (String, required): ID of the query

And all [create options][query-create].

Usage

await consul.query.update({
  query: '422b14b9-874b-4520-bd2e-e149a42b0066',
  name: 'redis',
  service: {
    service: 'redis'
    onlypassing: false
  },
});

consul.query.get(options)

Get prepared query.

Options

query (String, required): ID of the query

Usage

await consul.query.get("6119cabf-c052-48fe-9f07-711762e52931");

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

consul.query.destroy(options)

Delete prepared query.

Options

query (String, required): ID of the query

Usage

await consul.query.destroy("422b14b9-874b-4520-bd2e-e149a42b0066");

consul.query.execute(options)

Execute prepared query.

Options

query (String, required): ID of the query

Usage

await consul.query.execute("6119cabf-c052-48fe-9f07-711762e52931");

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

consul.query.explain(options)

Explain prepared query.

Options

query (String, required): ID of the query

Usage

await consul.query.explain("422b14b9-874b-4520-bd2e-e149a42b0066");

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

consul.session

consul.session.create([options])

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-86400s): interval session must be renewed

Usage

await consul.session.create();

Result

{
  "ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1"
}

consul.session.destroy(options)

Destroy a given session.

Options

id (String): session ID
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.session.destroy("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");

consul.session.get(options)

Queries a given session.

Options

id (String): session ID
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.session.get("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");

Result

{
  "CreateIndex": 11,
  "ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
  "Name": "",
  "Node": "node1",
  "Checks": ["serfHealth"],
  "LockDelay": 15000000000
}

consul.session.node(options)

Lists sessions belonging to a node.

Options

node (String): node
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.session.node("node1");

Result

[
  {
    "CreateIndex": 13,
    "ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
    "Name": "",
    "Node": "node1",
    "Checks": ["serfHealth"],
    "LockDelay": 15000000000
  }
]

consul.session.list([options])

Lists all the active sessions.

Options

dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.session.list();

Result

[
  {
    "CreateIndex": 15,
    "ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
    "Name": "",
    "Node": "node1",
    "Checks": ["serfHealth"],
    "LockDelay": 15000000000
  }
]

consul.session.renew(options)

Renew a given session.

Options

id (String): session ID
dc (String, optional): datacenter (defaults to local for agent)

Usage

await consul.session.renew("a0f5dc05-84c3-5f5a-1d88-05b875e524e1");

Result

[
  {
    "CreateIndex": 15,
    "ID": "a0f5dc05-84c3-5f5a-1d88-05b875e524e1",
    "Name": "",
    "Node": "node1",
    "Checks": ["serfHealth"],
    "LockDelay": 15000000000,
    "Behavior": "release",
    "TTL": ""
  }
]

consul.status

consul.status.leader()

Returns the current Raft leader.

Usage

await consul.status.leader();

Result

"127.0.0.1:8300"

consul.status.peers()

Returns the current Raft peer set.

Usage

await consul.status.peers();

Result

["127.0.0.1:8300"]

consul.transaction.create(operations)

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

await consul.transaction.create([
  {
    {
      KV: {
        Verb: 'set',
        Key: 'key1',
        Value: Buffer.from('value1').toString('base64')
      }
    },{
      KV: {
        Verb: 'delete',
        Key: 'key2'
      }
    }
  }
]);

consul.watch(options)

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

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

Acceptance Tests

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

License

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Consul

Documentation

Consul([options])

Common Method Call Options

consul.acl

consul.acl.bootstrap()

consul.acl.replication([options])

consul.acl.legacy

consul.acl.legacy.create([options])

consul.acl.legacy.update(options)

consul.acl.legacy.destroy(options)

consul.acl.legacy.get(options)

consul.acl.legacy.clone(options)

consul.acl.legacy.list([options])

consul.agent

consul.agent.members([options])

consul.agent.reload([options])

consul.agent.self()

consul.agent.maintenance(options)

consul.agent.join(options)

consul.agent.forceLeave(options)

consul.agent.check

consul.agent.check.list()

consul.agent.check.register(options)

consul.agent.check.deregister(options)

consul.agent.check.pass(options)

consul.agent.check.warn(options)

consul.agent.check.fail(options)

consul.agent.service

consul.agent.service.list()

consul.agent.service.register(options)

consul.agent.service.deregister(options)

consul.agent.service.maintenance(options)

consul.catalog

consul.catalog.register(options)

consul.catalog.deregister(options)

consul.catalog.datacenters()

consul.catalog.connect

consul.catalog.connect.nodes(options)

consul.catalog.node

consul.catalog.node.list([options])

consul.catalog.node.services(options)

consul.catalog.service

consul.catalog.service.list([options])

consul.catalog.service.nodes(options)

consul.event

consul.event.fire(options)

consul.event.list([options])

consul.health

consul.health.node(options)

consul.health.checks(options)

consul.health.service(options)

consul.health.state(options)

consul.kv

consul.kv.get(options)

consul.kv.keys(options)

consul.kv.set(options)

consul.kv.del(options)

consul.query

consul.query.list()

consul.query.create(options)

consul.query.update(options)

consul.query.get(options)

consul.query.destroy(options)

consul.query.execute(options)

consul.query.explain(options)

consul.session

consul.session.create([options])

consul.session.destroy(options)

consul.session.get(options)

consul.session.node(options)

consul.session.list([options])

consul.session.renew(options)

consul.status