Hiera AWS Secrets Manager Backend 🔑

A hiera backend to query AWS Secrets Manager which uses Puppet Environments for namespacing.

$ hiera 'my_system/password' \
    environment=prod \
    --config ~/hiera.yaml \
    --debug

DEBUG: 2018-08-30 16:54:00 +0000: AWS Secrets Manager backend starting
DEBUG: 2018-08-30 16:54:00 +0000: Retrieved Secret 'production/my_system/password' with version '2d06f591-ef4c-4e4e-8c6c-5e3668db9180'

mYs3cR3TpAs5W0rD

• Install
• Supported Lookups
• Configuration
  • Region
  • Credentials
  • Environments
• Contributing
  • Code of Conduct
  • Getting Started
  • Building
  • Releasing a Change
• License

To install the gem manually:

gem install hiera-secrets-manager

Install the dependencies before attempting to use the gem:

bundle install

hiera-secrets-manager supports :priority (single value) and :hash (key-value pair) lookups, but not :array.

# In environment 'production' with 'production/system/my-secret' set as 'some-password'
$secret = hiera('system/my-secret')

notice($secret) # prints 'Notice: Scope(Class[main]): some-password'

# In environment 'production' with 'production/system/my-secret' set as pairs 'foo:bar' and 'baz:zap'
$secret = hiera_hash('system/my-secret')

notice($secret['foo']) # prints 'Notice: Scope(Class[main]): bar'
notice($secret['baz']) # prints 'Notice: Scope(Class[main]): zap'

notice($secret) # prints 'Notice: Scope(Class[main]): {"foo"=>"bar", "baz"=>"zap"}'

Hiera Secrets Manager is configurable and the configuration has three required fields to operate: region, access_key_id, and secret_access_key.

An example hiera.yaml file implementing only hiera-secrets-manager is below:

:backends:
  - secrets_manager
:secrets_manager:
    :region: eu-west-1
    :access_key_id: AWSACCESSKEY
    :secret_access_key: rAnd0MsTr!nG
    :environments:
        dev: development
        uat: staging
        prod: production

Mandatory field. Corresponds to AWS Region where your secrets are stored e.g. eu-west-1

Credentials for the AWS user are mandatory. The user must have permission to use secretsmanager:GetSecretValue on any relevant secrets in AWS Secrets Manager. This permission can be configured in AWS IAM.

Mandatory field. Corresponds to AWS's Access key ID.

Mandatory field. Corresponds to AWS's Secret access key.

Optional field. When used with Puppet, an environment will always be present. These key value pairs map the environments in Puppet to namespaces in AWS.

:environments:
    dev: development
    uat: staging
    prod: production

• A lookup for key foo in environment dev will query AWS Secrets Manager for development/foo

If there is no key set for an environment, or no environments configuration at all, the secret name that will be queried in AWS Secrets Manager will by default be prefixed with the Puppet environment name:

• A lookup for key zap in environment test will query AWS Secrets Manager for test/zap, because there's no entry for test in the environments configuration.

Everyone interacting with this project is required to follow the Code of Conduct.

You'll need Git, Ruby, and Bundler installed. Then clone this project, and install its dependencies:

$ git clone git@github.com:unruly/hiera-secrets-manager
$ bundle install

You can run rake in the project root to run RSpec tests, and check test coverage.

• To build a gem on your local machine, run gem build hiera-secrets-manager.gemspec, which will create a .gem file with the current version number.
• Install the gem with gem install hiera-secrets-manager-{VERSION}.gem, specifying the version number.

• To release a new version:
  • Update the version number in hiera-secrets-manager.gemspec
  • Ensure versions are in line with the Semantic Versioning convention.
  • Open a pull request against this repository.

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