aws-param-store

Module for loading parameter-store values from AWS SSM

Features

• Gets parameters by name(s) or path
• Recursively resolves paths and decodes parameters by default
• Paginates results automatically
• Supports both synchronous and asynchronous querying of parameters
• Uses Promises for asynchronous calls
• Can run inside AWS Lambda environment
• AWS Lambda Node.js 8.10.x compatible
• Lightweight and does not require additional dependencies other than the AWS-SDK

Installation

Install via npm.

npm install aws-param-store --save

Note: aws-param-store does not contain a dependency on aws-sdk and it should be installed within your application.

Getting Started

const awsParamStore = require( 'aws-param-store' );

awsParamStore.getParametersByPath( '/project1/service1/production' )
    .then( (parameters) => {

        // do something here
    });

If your AWS region is not set in your environment variables, then it can be set programmatically by supplying options when calling newQuery():

const awsParamStore = require( 'aws-param-store' );

awsParamStore.getParametersByPath( '/project1/service1/production', { region: 'us-east-1' } )
    .then( (parameters) => {

        // do something here
    });

API

Overview

Most API method calls in this library have both asynchronous and synchronous versions. When an asynchronous version is called, a Promise is returned to resolve the value once the operation completes. When an options parameter is allowed, it can be used to specify specific AWS service options such as the region. All of the getParameter* methods will request that the values are decoded. If you require further control, please use the parameterQuery() method.

getParameter( name [, options] )

Gets a parameter by name. This method returns a promise that resolves the Parameter.

const awsParamStore = require( 'aws-param-store' );

awsParamStore.getParameter( '/project1/my-parameter', { region: 'us-east-1' } )
    .then( (parameter) => {

        // Parameter info object for '/project1/my-parameter'
    });

getParameterSync( name [, options] )

Gets a parameter by name. This method will block until the operation completes.

const awsParamStore = require( 'aws-param-store' );

let parameter = awsParamStore.getParameterSync( '/project1/my-parameter',
											{ region: 'us-east-1' } );

// Parameter info object for '/project1/my-parameter'

getParameters( names [, options] )

Gets one or more parameters by name. This method returns a promise that resolves an object that contains Parameters and InvalidParameters.

const awsParamStore = require( 'aws-param-store' );

awsParamStore.getParameters( ['/project1/my-parameter1', '/project1/my-parameter2'],
							 { region: 'us-east-1' } )
    .then( (results) => {

        // results.Parameters will contain an array of parameters that were found
		// results.InvalidParameters will contain an array of parameters that were
		//                           not found
    });

getParametersSync( names [, options] )

Gets one or more parameters by name. This method will block until the operation completes, and will return an object that contains Parameters and InvalidParameters.

const awsParamStore = require( 'aws-param-store' );

let results = awsParamStore.getParametersSync( ['/project1/my-parameter1', '/project1/my-parameter2'],
							     			   { region: 'us-east-1' } );

// results.Parameters will contain an array of parameters that were found
// results.InvalidParameters will contain an array of parameters that were
//                           not found

getParametersByPath( path [, options] )

Gets parameters by recursively traversing the supplied path. This method returns a promise that resolves the parameters that were found.

const awsParamStore = require( 'aws-param-store' );

awsParamStore.getParametersByPath( '/project1' )
    .then( (parameters) => {

		// parameters contains an array of parameter objects
    });

getParametersByPathSync( path [, options] )

Gets parameters by recursively traversing the supplied path. This method will block until the operation completes, and will return a list of matching parameters.

const awsParamStore = require( 'aws-param-store' );

let parameters = awsParamStore.getParametersByPathSync( '/project1' );

// parameters contains an array of parameter objects

putParameter( name, value, type [, options] )

Puts parameter. This method returns a promise that resolves to the version returned back.

const awsParamStore = require( 'aws-param-store' );

awsParamStore.putParameter('key', 'value1,value2', 'StringList', {region: 'us-east-1', Overwrite: false})
    .then( (results) => {

		// results is the version of the value created
    });

putParameterSync( name, value , type [, options] )

Puts parameter. This method. This method will block until the version returned back.

const awsParamStore = require( 'aws-param-store' );

let results = awsParamStore.putParameterSync('key', 'securedstring', 'SecureString', {region: 'us-east-1'});

ParameterQuery

Instances of ParameterQuery can be created by calling parameterQuery( [options] ). This object is implementation behind the getParameter* methods, and allows further control over how the calls are made to resolve parameters.

ParameterQuery.path( p )

Sets the path name not be queried. Returns a reference to the ParameterQuery instance.

ParameterQuery.named( name )

Sets the name or names (if an array) to be queried. Returns a reference to the ParameterQuery instance.

ParameterQuery.decryption( enabled = true )

Indicates that the decryption of the values is enabled/disabled. Returns a reference to the ParameterQuery instance.

ParameterQuery.recursive( enabled = true )

Enables or disables recursive operations when resolving parameters by path. Returns a reference to the ParameterQuery instance.

ParameterQuery.execute()

Executes the query based on path or name(s) that were selected. Returns a Promise that resolves the parameter results.

ParameterQuery.executeSync()

Executes the query based on path or name(s) that were selected. This operation will block until complete.

Feedback

We'd love to get feedback on how to make this tool better. Feel free to contact us at [email protected]

License

BSD-3-Clause