Spring-like Cloud Config for NodeJS Applications

NodeJS application configuration using similar style to Spring Config and using the Spring Cloud Config Server for remote property sources.

Depends on cloud-config-client for the config server client functionality.

Feature requests are welcome.

Introduction

You get to define your application properties the same way you do in your Spring Boot applications. Use a bootstrap.yml file to specify your config server settings and application.yml to hold your local application properties. This module even supports profiling, similar to Spring Boot profiles, giving you the option to define profile-based properties in either separate files, like application-{profile}.yml, or in a single multi-document yaml file using a profiles property on the applicable documents, like profiles: profile1,profile2.

Getting Started

Install the package

npm install spring-cloud-config

Define an application.yml, or a group of application.yml and application-{profile}.yml files, in the location of your choice.

application.yml

spring.cloud.config.name: my-application-name
db:
   mongo:
      url: http://localhost:27017
---
profiles: dev1,dev2
db:
   mongo:
      url: http://dev-mongo-server:27017

Define a bootstrap.yml in the location of your choice.

bootstrap.yml

spring:
   cloud:
      config:
         enabled: true
         endpoint: http://localhost:8888
         label: master
---
profiles: dev1,dev2
spring.cloud.config.endpoint: http://dev-config-server:8888

Load your configuration during startup/initialization.

const SpringCloudConfig = require('spring-cloud-config');

const configOptions = {
    configPath: __dirname + '/config',
    activeProfiles: ['dev1'],
    level: 'debug'
};
let myConfig;

SpringCloudConfig.load(configOptions).then(theConfig => {
   myConfig = theConfig;
   // now run your application with the loaded config props.
   // do this by saving the returned config object somewhere,
   // or by using the SpringCloudConfig.instance() helper.
);

Use the config later on in your code.

const SpringCloudConfig = require('spring-cloud-config');

const myConfig = SpringCloudConfig.instance();
console.log(`My Mongo DB URL: ${myConfig.db.mongo.url}`);

Using typescript? No problem...

import { Config, CloudConfigOptions, ConfigObject } from 'spring-cloud-config';

const cloudConfigOptions: CloudConfigOptions = {
    configPath: __dirname + '/config',
    activeProfiles: ['dev1'],
    level: 'debug'
};

let myConfig: ConfigObject;

Config.load(cloudConfigOptions).then((theConfig: ConfigObject) => {
   myConfig = theConfig;
   // now run your application with the loaded config props.
   // do this by saving the returned config object somewhere,
   // or by using the Config.instance() helper.
);

Now you can use the config properties later on.

import { Config } from 'spring-cloud-config';

console.log(`My Mongo DB URL: ${Config.instance().db.mongo.url}`);

Things Explained

The Yaml Files

As mentioned above, this module uses Yaml files to configure your application properties. You need to supply folder paths where it can expect to find two sets of files: bootstrap.yml and application.yml. The bootstrap yaml is used to configure your cloud config server properties, similar to Spring Cloud Config. The application yaml should be used for defining your application's configuration properties. Optionally, you can specify your application's name in application.yml instead of in bootstrap.yml, using the spring.cloud.config.name property. Doing so gives you the option of using a shared bootstrap.yml (i.e. shared with other apps) but still be able to specify your individual application's name.

Support for Profiles in Multi-Document Yaml

As with any Yaml implementation you can include multiple documents in a single Yaml file, using --- as a separator. Additionally, this module allows you to define documents that apply to specific 'profiles', same as the 'spring.profiles' concept. If you include a profiles property in a given yaml document, the properties in that document will only be included in your merged configuration result if any of the configOptions.activeProfiles match up with the specified profiles.

Example application.yml

spring.cloud.config.name: my-application-name
db:
   mongo:
      url: http://localhost:27017
---
profiles: dev1,dev2,!local
db:
   mongo:
      url: http://dev-mongo-server:27017

Applying Yaml Docs to Multiple Profiles

You can apply the properties of a Yaml doc to multiple application profiles. Just provide a comma separated string of profile names in the doc's profiles property, like profiles: dev1,dev2.

Excluding Yaml Docs from Profiles

This module supports the Not operator (!) on profiles to provide for excluding configuration properties from specific profiles. Just prepend an '!' to the profile name you want to exclude the given yaml doc from, like profiles: dev1,!dev2.

Support for Profile-Specific File Names

If your application supports a wide range of profiles and/or properties then you might consider using profile-specific file names for your application.yml. Wherever you keep your application.yml, just add more yaml files named with this pattern: application-{profile}.yml.

Examples

application.yml
application-local.yml
application-dev.yml
application-dev2.yml
application-prod.yml

Node Env Property Sources

This module provides some pre-defined properties/property sources from the Node env. This enables you to exclude sensitive data from your repository files and instead provide them using environment variables. For example, you might want to exclude the username and password used for authenticating with your remote config server from your git repo.

When set, node env variables will be mapped to their respective config properties during the bootstrap phase. Be aware, env variables take highest precedence so they'll override whatever value is provided from other sources.

Pre-Defined Env Variable Mappings

Env Variable Name	Type	Usage
SPRING_CONFIG_ENDPOINT	string	Maps to spring.cloud.config.endpoint. Example: SPRING_CONFIG_ENDPOINT=http://test:8888 node index.js
SPRING_CONFIG_AUTH_USER	string	Maps to spring.cloud.config.auth.user. Example: SPRING_CONFIG_AUTH_USER=user1 node index.js
SPRING_CONFIG_AUTH_PASS	string	Maps to spring.cloud.config.auth.pass. Example: SPRING_CONFIG_AUTH_PASS=user1password node index.js
APPLICATION_JSON	Stringified JSON Object	When APPLICATION_JSON is set in Node env, the value will be read into the application's configuration as a high priority set of properties. Example: APPLICATION_JSON='{ "testProp": "testValue" }' node index.js

Remote Property Sources

If you enable the use of spring cloud config via the bootstrap property spring.cloud.config.enabled: true, the properties in application.yml will be overridden by any of the same properties defined in your remote sources. Keep in mind, however, any error encountered while reaching the remote property sources will be ignored, unless you set the bootstrap property spring.cloud.config.fail-fast: true. As a best practice, it is recommended that the properties defined in application.yml be kept up to date and represent the most current state of the application (as much as reasonably possible).

Cloud Config Client Fail Fast

If you need spring-cloud-config to throw an error when it can't reach the cloud config server, set the bootstrap property spring.cloud.config.fail-fast: true. Combine this with enabling retry (see below) to provide some resiliency to your cloud configuration retrieval.

Cloud Config Client Retry

If you'd like spring-cloud-config to retry connecting to your cloud config server after a failure, set the bootstrap property spring.cloud.config.retry.enabled: true, in addition to setting fail-fast to true (see above). When retry is enabled, spring-cloud-config will retry the config server connection based on the retry configuration you provide, or based on the default configuration. Below are the retry properties and their defaults. See the API specs further down for details.

• spring.cloud.config.retry.enabled: false
• spring.cloud.config.retry.max-attempts: 6
• spring.cloud.config.retry.max-interval: 1500 (ms)
• spring.cloud.config.retry.initial-interval: 1000 (ms)
• spring.cloud.config.retry.multiplier: 1.1

API

load function

Reads all defined property sources, including remote cloud config properties (if enabled), and returns the merged configuration properties object.

Parameter	Type	Description
options	Object	(Required) Holds the options properties that help you configure the behavior of this module.
options.bootstrapPath	String	(Optional) The folder path to your bootstrap config file. If not provided, then options.configPath location must contain both bootstrap.yml and application.yml.
options.configPath	String	(Required) The folder path to your yaml config file(s).
options.activeProfiles	String[]	(Required) Profile names to filter your local yaml documents, as well as your remote property sources, by.
options.level	String	(Optional) Logging level to use.

instance function

Returns the current configuration properties object. Use the load function prior to using this.

bootstrap.yml Cloud Config Options

Option	Type	Description
spring.cloud.config	object	(Required) The config options to use for fetching remote properties from a Spring Cloud Config Server.
spring.cloud.config.enabled	boolean	(Required) Enable/disable the usage of remote properties via a Spring Cloud Config Server.
spring.cloud.config.fail-fast	boolean	(Optional, Default: false) Enable/disable throwing an error when remote config retrieval fails.
spring.cloud.config.retry	object	(Optional) Controls the retry logic for remote configuration retrieval.
spring.cloud.config.retry.enabled	boolean	(Optional, Default: false) Enable/disable retry. If enabled, retrieval of remote configuration properties will be retried if it fails. See additional properties below.
spring.cloud.config.retry.max-attempts	number	(Optional, Default: 6) Maximum times to retry.
spring.cloud.config.retry.max-interval	number	(Optional, Default: 1500) Maximum interval in milliseconds to wait between retries.
spring.cloud.config.retry.initial-interval	number	(Optional, Default: 1000) Initial interval in milliseconds to wait before the first retry.
spring.cloud.config.retry.multiplier	number	(Optional, Default: 1.1) Factor by which the retry interval will increase between retries.
profiles	string	(Optional) Comma separated string of profiles. Indicates which profiles the properties in the current yaml document apply to.
spring.cloud.config.name	String	(Optional) The application name to be used for reading remote properties. Alternatively, if not provided here, this must be specified in your application.yml.
spring.cloud.config.endpoint	String	(Optional, Default: http://localhost:8888) The url endpoint of the Spring Cloud Config Server.
spring.cloud.config.label	String	(Optional, Default: master) The cloud config label to use.
spring.cloud.config.rejectUnauthorized	boolean	(Optional, Default: true) if false accepts self-signed certificates
spring.cloud.config.auth	Object	(Optional) Basic Authentication for config server (e.g.: { user: "username", pass: "password"}). endpoint accepts also basic auth (e.g. http://user:pass@localhost:8888).
spring.cloud.config.auth.user	string	(Required) username if using auth
spring.cloud.config.auth.pass	string	(Required) password if using auth

application.yml Application Config Properties

Option	Type	Description
spring.cloud.config.name	String	(Optional) You can override/specify your application name here, or in bootstrap.yml. This is an option so that you can share bootstrap.yml with other applications but still use your own application name.
profiles	string	(Optional) Comma separated string of profiles. Indicates which profiles the properties in the current yaml document apply to.
any.property.you.need	?	This is where you define whatever properties your application needs to be awesome!