envman

A little environment manager for AWS SSM / ParameterStore / Dotenv

 __ _ ____ ___ __ ___ __ _ _ __ _ __
/ _ \ '_ \ \ / / '_ ` _ \ / _` | '_ \
| __/ | | \ V /| | | | | | (_| | | | |
\___|_| |_|\_/ |_| |_| |_|\__,_|_| |_|

How to install

Before install

envman is hosted in a private NPM repository, so make sure you have access to handstudio's private repo. check out your $HOME/.npmrc file.

@handstudio:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=GITHUB_TOKEN

Install locally, as a library

npm install --save @handstudio/envman

Install globally, as a CLI utility

npm install -g @handstudio/envman

Usages

Keys of environment variables

Prints a list of all environment variable keys.

# envman keys
envman keys

Printing environment variables

Assume that there are stored environment variables in AWS ParameterStore. you can env-variables like followings:

# envman print --key <key>
envman print \
  --key /NCDinos/BatchWorker/Stage \

  --output json \
  --profile someAwsProfileName

The --output flag can be one of json, dotenv, ebextensions.

It is also possible to read environment variables from multiple keys.

# envman print --key <key1> --key <key2>
envman print \
  --key /NCDinos/BatchWorker/Stage \
  --key /NCDinos/Common/Stage \

  --output json \
  --profile someAwsProfileName

If you're using AWS STS with MFA(Multi Factor Authorization), use --use-mfa flag.

envman print \
  --key /Test/Stage \
  --use-mfa

Saving environment variables into storage

Parameter can be saved in environment variable storage through --env: KEY VALUE command.

# envman save <key> --env:K1 V1 --env:K2 V2 ...
envman save /NCDinos/Common \
  --env:MASTER_KEY somemasterkey \
  --env:IV someiv \
  --profile ncdinos

Suppose that the environment variables are stored in the form of a dotenv file locally. You can store it in a remote environment variable repository as follows:

# envman save <key> --input [dotenv | json] --path <path>
envman save /NCDinos/Common \
  --input dotenv \
  --path $HOME/test-env.env \
  --profile ncdinos

The --input flag can have the following values: json, dotenv

Usage with node.js projects

With shell script

env \
  $(envman print \
    --key /ncdinos/auction-mall/stage \
    --profile ncdinos \
  ) node app.js

Of course, you can also use ENVMAN as a npm script as follows. The following sample package.json shows that using ENVMAN and node.js project together.

{
  "name": "env-test",
  "version": "1.0.0",
  "description": "envman test project",
  "main": "app.js",
  "scripts": {
    "start": "env $(envman print --key /ncdinos/auction-mall/stage --profile ncdinos) node app.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "dependencies": {},
  "devDependencies": {
    "@handstudio/envman": "^1.0.1"
  }
}

With node --require option

You can use the following method inspired by dotenv.

ENVMAN_KEY=/NCDinos/Common \
  node -r @handstudio/envman/config yourApp.js

By using ENVMAN_KEY, you can specify the key of the environment variable you want to load. If you need a separate AWS profile name, you can use it as follows by using ENVMAN_AWS_PROFILE :

ENVMAN_KEY=/NCDinos/Common \
ENVMAN_AWS_PROFILE=ncdinos \ # your AWS profile name
  node -r @handstudio/envman/config yourApp.js

Loading environment variables is basically an asynchronous operation. for this reason, it is necessary to use a slightly tricky method to use it with the --require flag of node.js. check out following example:

const { waitUntilLoaded } = require('@handstudio/envman');

// Your App Entrypoint

(async () => {
  console.log('Waiting for envman ...');
  await waitUntilLoaded(); // waits until ENVMAN loading complete

  console.log('App started!');
  console.log(process.env); // At this moment, ENVMAN will be finished loading all environment variables.
})();

Function references

async fetchEnvironments(keys: string[])

Loads the environment variables from remote store. returns Promise<Environments>.

async storeEnvironments(key: string, envs: Environments)

Saves the environment variables to remote store.

async waitUntilLoaded()

Waits for environment variable loading to complete.

Roadmap

TBD