ParamStore

This gem goal is to ~~DRY some code I have been copying around for a while~~ make easy switching in between ENV, AWS Parameter Store (SSM), AWS Secrets Manager and EJSON for retrieving parameters.

This gem is not a replacement for dotenv. I still use and recommend it in development, in case it is "safe" to save your keys in .env files.

Installation

Add this line to your application's Gemfile:

gem 'param_store'

Usage

Configuring adapters

Available adapters: :env, :aws_ssm, :aws_secrets_manager and :ejson_wrapper.

ParamStore.adapter = adapter

Retrieving parameters

# ParamStore.fetch is similar to Hash#fetch,
# If the key is not found and there's no default given, it will raise a `KeyError`
ParamStore.fetch('name')
ParamStore.fetch('name', 'default value')
ParamStore.fetch('name') { 'default value' }

Copying from any adapter to ENV

ParamStore.copy_to_env('name1', 'name2', 'name3')

ENV['name1'] # => value for name1
ENV['name2'] # => value for name2
ENV['name3'] # => value for name3

Adapters

ENV

ParamStore.adapter :env

AWS Parameter Store (SSM)

Add to your Gemfile:

gem 'aws-sdk-ssm', '~> 1'

Configure the adapter:

ParamStore.adapter :aws_ssm, default_path: '/Prod/App/'

Retrieving parameters

ParamStore.fetch('name')
# => get parameter name, if default_path /Prod/App/ get parameter /Prod/App/name
ParamStore.fetch('name', path: '/Prod/App/')
# => get parameter /Prod/App/name

Copying from SSM adapter to ENV

ParamStore.copy_to_env('name1', 'name2', 'name3', path: '/Environment/Type of computer/Application/')
# path overrides default_path

ENV['name1'] # => value for name1
ENV['name2'] # => value for name2
ENV['name3'] # => value for name3

SSM client

By default ParamStore will initiate Aws::SSM::Client.new without supplying any argument. If you want to control the initiation of the SSM client, you can define it by setting ssm_client.

ParamStore.ssm_client = Aws::SSM::Client.new(
  region: region_name,
  credentials: credentials,
  # ...
)

CLI

A few useful aws ssm commands:

aws ssm get-parameters-by-path --path /Prod/ERP/SAP --with-decryption
aws ssm put-parameter --name /Prod/ERP/SAP --value ... --type SecureString

Secrets Manager

Add to your Gemfile:

gem 'aws-sdk-secretsmanager', '~> 1'

Configure the adapter:

ParamStore.adapter :aws_secrets_manager
# ParaStore.fetch('secret_id')
# => {\n  \"password\":\"pwd\"\n}\n

ParamStore.adapter :aws_secrets_manager, default_secret_id: 'secret_id'
# ParaStore.fetch('password')
# => pwd

Retrieving parameters

ParamStore.fetch('secret_id')
ParamStore.fetch('password', secret_id: 'secret_id')

Copying from Secrets Manager adapter to ENV

ParamStore.copy_to_env('key1', 'key2', 'key3', secret_id: 'secret_id')
# secret_id overrides default_secret_id

ENV['key1'] # => value for key1
ENV['key2'] # => value for key2
ENV['key3'] # => value for key3

EJSON

Add to your Gemfile:

gem 'ejson_wrapper', '~> 0.3.1'

Configure the adapter:

ParamStore.adapter(
  :ejson_wrapper,
  file_path: '...',
  key_dir: '...',
  private_key: '...',
  use_kms: '...',
  region: '...'
)
# see https://github.com/envato/ejson_wrapper#usage

Rails

If you are using ParamStore in prod and dotenv in dev:

# config/application.rb
# Bundler.require(*Rails.groups)
if Rails.env.production?
  ParamStore.adapter(:aws_ssm)
  ParamStore.copy_to_env('DATABASE_URL', require_keys: true, path: '/Prod/MyApp/')
else
  Dotenv::Railtie.load
end

Fail-fast

You can configure the required parameters for an app and fail at startup.

# config/application.rb
# Bundler.require(*Rails.groups)
ParamStore.require_keys!('key1', 'key2', 'key3')
# this will raise an error if any key is missing

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/phstc/param_store. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ParamStore project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.