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

Contents

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

Install

To install the gem manually:

gem install hiera-secrets-manager

Install the dependencies before attempting to use the gem:

bundle install

Supported Lookups

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

Priority Lookup

# 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'

Hash Lookup

# 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"}'

Configuration

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

Region

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

Credentials

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.

access_key_id

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

secret_access_key

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

Environments

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.

Contributing

Code of Conduct

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

Getting Started

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

$ git clone [email protected]:unruly/hiera-secrets-manager
$ bundle install

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

Building

• 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.

Releasing a Change

• 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.

License

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