A hiera backend for access to secrets being stored in HashiCorp Vault
Branch: master
Clone or download
petems Merge pull request #30 from kokovikhinkv/master
fix vault.address message
Latest commit 176b5f7 Feb 5, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/puppet/functions fix vault.address message Feb 5, 2019
spec Re-adds caching vault object logic Jan 6, 2019
.gitattributes PDK conversion Jan 10, 2019
.gitignore PDK conversion Jan 10, 2019
.pdkignore PDK conversion Jan 10, 2019
.rspec PDK conversion Jan 10, 2019
.rubocop.yml Big Refactor Dec 17, 2018
.travis.yml Big Refactor Dec 17, 2018
.yardopts PDK conversion Jan 10, 2019
CONTRIBUTING.md Big Refactor Dec 17, 2018
Gemfile PDK conversion Jan 10, 2019
Gemfile.lock PDK conversion Jan 10, 2019
LICENSE initial checkout May 11, 2017
README.md Add debouncer instructions Dec 30, 2018
Rakefile PDK conversion Jan 10, 2019
metadata.json PDK conversion Jan 10, 2019


hiera_vault : a vault data provider function (backend) for Hiera 5


Warning: master may be broken whilst this repo is upgraded for k/v v2 and newer Vault version upgrades! Please use the 0.1.0 tagged release in the meantime. This message will be removed and a 1.0.0 breaking release will be tagged on the Forge in the future.

This is a back end function for Hiera 5 that allows lookup to be sourced from Hashicorp's Vault.

Vault secures, stores, and tightly controls access to tokens, passwords, certificates, API keys, and other secrets in modern computing. Vault handles leasing, key revocation, key rolling, and auditing. Vault presents a unified API to access multiple backends: HSMs, AWS IAM, SQL databases, raw key/value, and more.

For an example repo of it in action, check out the hashicorp/webinar-vault-hiera-puppet repo and webinar 'How to Use HashiCorp Vault with Hiera 5 for Secret Management with Puppet'


  • This moduel is only compatible with Hiera 5 (ships with Puppet 4.9+) and Vault KV engine version 2 (Vault 0.10+)


The vault gem must be installed and loadable from Puppet

# /opt/puppetlabs/puppet/bin/gem install vault
# puppetserver gem install vault

On Puppetserver <= 5, you will need to switch Puppetserver to use the new JRuby 9K, as the gem requires Ruby 2+, and Puppetserver uses the 1.9.2 JRuby

Some example Puppetcode to do so:

ini_setting { "Change jruby to 9k":
  ensure            => present,
  setting           => 'JRUBY_JAR',
  path              => "/etc/sysconfig/puppetserver",
  key_val_separator => '=',
  section           => '',
  value             => '"/opt/puppetlabs/server/apps/puppetserver/jruby-9k.jar"',
  show_diff         => true,
  notify            => Service['puppetserver']

package { 'vault-puppetserver-gem':
  ensure   => 'present',
  name     => 'vault',
  provider => 'puppetserver_gem',
package { 'vault-puppetpath-gem':
  ensure   => 'present',
  name     => 'vault',
  provider => 'puppet_gem',
package { 'debouncer-puppetserver-gem':
  ensure   => 'present',
  name     => 'debouncer',
  provider => 'puppetserver_gem',
package { 'debouncer-puppetpath-gem':
  ensure   => 'present',
  name     => 'debouncer',
  provider => 'puppet_gem',
~> Service['puppetserver']

On Puppetserver >= 6, this is not needed as the default has been moved to the newer JRuby.


The data provider is available by installing the petems/hiera_vault module into your environment:

This will avaliable on the forge, and installable with the module command:

# puppet module install petems/hiera_vault

You can also download the module directly:

git clone https://github.com/petems/petems-hiera_vault /etc/puppetlabs/code/environments/production/modules/hiera_vault

Or add it to your Puppetfile

mod 'hiera_vault',
  :git => 'https://github.com/petems/petems-hiera_vault'

Hiera Configuration

See The official Puppet documentation for more details on configuring Hiera 5.

The following is an example Hiera 5 hiera.yaml configuration for use with hiera-vault


version: 5

  - name: "Hiera-vault lookup"
    lookup_key: hiera_vault
        - '^vault_.*'
        - '^.*_password$'
        - '^password.*'
      ssl_verify: false
      address: https://vault.foobar.com:8200
      token: <insert-your-vault-token-here>
      default_field: value
          - %{::trusted.certname}
          - common

The following mandatory Hiera 5 options must be set for each level of the hierarchy.

name: A human readable name for the lookup

lookup_key: This option must be set to hiera_vault

The following are optional configuration parameters supported in the options hash of the Hiera 5 config

address: The address of the Vault server, also read as ENV["VAULT_ADDR"]

token: The token to authenticate with Vault, also read as ENV["VAULT_TOKEN"] or a full path to the file with the token (eg. /etc/vault_token.txt). When bootstrapping, you can set this token as IGNORE-VAULT and the backend will be stubbed, which can be useful when bootstrapping.

confine_to_keys:: Only use this backend if the key matches one of the regexes in the array, to avoid constantly reaching out to Vault for every parameter lookup

    - "application.*"
    - "apache::.*"

default_field:: The default field within data to return. If not present, the lookup will be the full contents of the secret data.

mounts:: The list of mounts you want to do lookups against. This is treated as the backend hiearchy for lookup. It is recomended you use Trusted Facts within the hierachy to ensure lookups are restricted to the correct hierachy points. See Mounts

:ssl_verify: Specify whether to verify SSL certificates (default: true)


puppet lookup vault_notify --explain --compile --node=node1.vm
Searching for "vault_notify"
  Global Data Provider (hiera configuration version 3)
    Using configuration "/etc/puppetlabs/code/hiera.yaml"
    Hierarchy entry "yaml"
      Path "/etc/puppetlabs/code/environments/production/hieradata/node1.yaml"
        Original path: "%{::hostname}"
        No such key: "vault_notify"
      Path "/etc/puppetlabs/code/environments/production/hieradata/common.yaml"
        Original path: "common"
        Path not found
  Environment Data Provider (hiera configuration version 5)
    Using configuration "/etc/puppetlabs/code/environments/production/hiera.yaml"
    Hierarchy entry "Hiera-vault lookup"
      Found key: "vault_notify" value: "hello123"

Vault Configuration

NOTE: Currently only kv version 1 is supported by hiera_vault. Support for v2 will require some changes upstream in the vault gem.


It is recomended to have a specific mount for your Puppet secrets, to avoid conflicts with an existing secrets backend.

From the command line:

vault secrets enable -version=1 -path=puppet kv

We will then configure this in our hiera config:

    - %{::trusted.certname}
    - common

Then when a hiera call is made with lookup on a machine with the certname of foo.example.com:

$cool_key = lookup({"name" => "cool_key", "default_value" => "No Vault Secret Found"})

Secrets will then be looked up with the following path: http://vault.example.com:8200/v1/puppet/foo.example.com/cool_key


  • Original - David Alden dave@alden.name
  • Transfered and maintained by Peter Souter