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.