Consulea

Load Consul keys, environment vars, and command line arguments in a predictable, standardized way.

Module goals:

• Compile single config object from Consul kv, environment variables, and command line arguments.
• Watch for changes in Consul prefix, send an event with updated config.
• Verify required variables are set.
• Be extremely light weight, having minimal dependencies.
• Predictable config key outcome given different standards of input variables using different sources.
• Simplify origin of keys in Consul and Env. Each project should have it's own namespace, nothing shared.
• No ES6 dependency, so it works under Node.js 0.10 and onward.

Variables are first read from Consul, then the environment, then command line arguments, allowing the user to override something already previously set in Consul. The config key webPort can be set by Consul key test-svc/web-port and can be overridden by environment variable TESTSVC_WEB_PORT, and both can be overridden by --web-port.

Install

npm install --save consulea

Example

// Load module
var Consulea = require('consulea');

// Create new instance of module, pass in config
var consulea = new Consulea({
    consulToken: '4fe3dee9-4148-404e-9928-d95cfb1e6947',
    consulPrefix: 'test-svc/',
    envPrefix: 'TESTSVC',
    requiredKeys: ['serverName', 'port'],
    ifMissingKeysOnUpdate: 'warn',
    defaultData: {
        maxConnects: "100",
        timeOutMs: "10000",
    },
});

// Store your config however you please.
var myConfig = {};

// This event is called every time the Consul namespace is updated and upon first start.
// "meta" will supply things like keysChanged, and initialLoad
consulea.on('update', function (err, data, meta) {
    myConfig = data;
});

// Continue starting up project, with all config loaded for the first time.
// This event is only called once.
consulea.on('ready', function (err, data) {
    // Proceed with starting up... open service ports, etc.
});

// Or, if callbacks are more your style...
consulea.callbackWhenReady(function (err){
    // Proceed with starting up... open service ports, etc.
});

// Handle errors and warnings as you see fit
consulea.on('error', function (err) {
    console.error('Consulea error:', err);
});

Config is now available to project from three different sources:

| Consul key | Env key | CLI key | Resulting variable | | - | - | - | - | | test-svc/port | TESTSVC_PORT | --port | port | | test-svc/server-name | TESTSVC_SERVER_NAME | --server-name | serverName | | test-svc/max-connects | TESTSVC_MAX_CONNECTS | --max-connects | maxConnects | | test-svc/time-out-ms | TESTSVC_TIME_OUT_MS | --time-out-ms | timeOutMs |

# Assuming Consul has all of the above keys configured,
# they can be overridden by the ENV variables by doing:
export TESTSVC_MAX_CONNECTS=100
export TESTSVC_SERVER_NAME="New staging server"
node someScript.js
# ... or inline:
TESTSVC_MAX_CONNECTS=100 TESTSVC_SERVER_NAME="New staging server" node someScript.js

# And they can be overridden again by using CLI arguments:
node someScript.js --max-connects=50 --server-name="Prod server"

Config object options

| Key | Required | Description | | - | - | - | | consulToken | No | ACL Token used to authenticate with Consul service | | consulPrefix | Yes | Namespace/prefix to search for keys in Consul | | envPrefix | No | Namespace/prefix to search for keys in local environment | | requiredKeys | No | List of camelCased keys which are considered to be required | | consulClientConfig | No | Consul config object, if you'd rather configure it yourself | | ifMissingKeysOnStartUp | No | Set behavior when required keys are missing on first start up (default: exit) | | ifMissingKeysOnUpdate | No | Set behavior when required keys are missing on any update after start up (default: exit) | | suppressErrors | No | Set true to prevent Consulea from emitting errors. The emitted error event will still occur | | defaultData | No | Pass in default KV data, which may be overwritten by Consul, ENV or command line arguments |

ifMissingKeysOnStartUp and ifMissingKeysOnUpdate can be one of the following:

• exit: Consulea will exit if any keys are missing.
• warn: Consulea will warn if any keys are missing.
• skip: Consulea will skip emitting the update/ready event if any keys are missing.
• lastGoodValue: Consulea will try to use the last good value for a given missing key and will exit if any keys did not previously exist.

Notes

The Consul host:port can be also be defined using the environment variable CONSUL_HTTP_ADDR. This may be helpful if code is running in Docker or the Consul agent isn't running on the local instance.

# Don't use localhost:8500, connect somewhere else
export CONSUL_HTTP_ADDR='https://remoteconsulserver.com:8500'
node someScript.js