node package manager



Build Status Dependency Status

This is a fork of etcd-registry to accomplish a few goals:

  • Use etcd-node
  • Use ES6
  • Allow service entries to be monitored for changes
  • Add more robust tests
  • Add linting and code coverage tests

Service registry for Node.js on top of etcd

npm install etcd-registry

To install the command line tool

npm install -g etcd-registry
etcd-registry help


import Registry from 'etcd-registry';
// Pass the nodes in your cluster in a connection string 
const services = new Registry(',,');
// Join the registry 
services.join({ name: 'my-service-name', service: { port: 8080 }});
// Wait a bit and do a lookup 
services.lookup('my-service-name', function(err, service) {
    console.log('Found the following service:');

Running the above example will produce the following output

Found the following service:
    name: 'my-service-name',
    port: 8080,
    hostname: '',
    host: '',
    url: ''

Full api

  • services = registry(connection-string) Create a new registry client
  • services = registry({ url: connection-url, maxRetries: 3, logger: loggerObject) Create a new registry client setting the maximum number of retries along with a Winston like logger object
  • services.join({ name, service, ttl }, [cb]) Join the registry with a new service
  • services.leave([name], [cb]) Leave the registry. Omit the name to remove local services
  • services.lookup(name, cb) Lookup a single service
  • services.list([name], cb) List all services as an array. Omit the name to list all services

Connection string

The connection has the following format


The protocol can be https or http and defaults to http. If you set a namespace all keys will be prefixed with the value. If you do not specify a port in the hosts 4001 will be used (default etcd port).


Services are just JSON documents. etcd-registry will add a default hostname and a couple of other properties. An example of a service document could be:

    name: 'my-service',
    port: 8080,
    hostname: '',       // added by etcd-registry 
    host: '',      // added by etcd-registry 
    url: '' // added by etcd-registry 

These documents are saved in etcd with a default TTL of 10s.

The TTL is able to be managed by setting the key ttl in the call to service.join().

On an interval of the half of the TTL etcd-registry will send a heartbeat for each service to the registry which resets the expiration counter.

If possible you should call services.leave() before exiting your service process. Otherwise your service will be garbage collected after the TTL.

Fault tolerance

If a operation fails etcd-registry will try another node in the cluster until it has tried everyone.

Every once in a while etcd-registry will ping your cluster to see if new machines has joined and update the connection string