Nerfing Powerful Megalomaniacs

    consul
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/consul package

    1.2.0 • Public • Published

    Consul

    This is a Consul client.

    Documentation

    See the official HTTP API docs for more information.

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

    or

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

    consul.catalog.datacenters()

    Lists known datacenters.

    Usage

    await consul.catalog.datacenters();

    Result

    ["dc1"]

    consul.catalog.connect

    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

    1. Install Consul into your PATH

      $ brew install consul
    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 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.

    Keywords

    Install

    npm i consul

    DownloadsWeekly Downloads

    78,095

    Version

    1.2.0

    License

    MIT

    Unpacked Size

    108 kB

    Total Files

    25

    Last publish

    Collaborators

    • silas