How to Use Hiera-Eyaml to Encrypt Your Sensitive Data

Hiera-eyaml makes it possible to securely store sensitive information (such as passwords) in Hiera, so not only will your confidential information be stored separately from your Puppet manifests, but you can also be sure it is safe.

Read on to find out how hiera-eyaml works and how you can use it to encrypt and manage your sensitive data files.

What is Hiera-Eyaml and How is it Used?

Hiera-eyaml is a backend for Hiera that can be used to encrypt sensitive data files in Puppet. 

If you’re already a bit familiar with Hiera, you know why it’s a good idea to separate your data from your Puppet manifests. In case you aren’t familiar, though, using Hiera-eyaml lets you write and use reusable manifests and modules. You store your organization-specific data in Hiera-eyaml, and then Puppet classes can request the data they need from your Hiera data store.

When facing the question of how to store your sensitive configuration data, such as passwords for your MySQL servers, the question is not why you should use Hiera-eyaml, but how.

Related: How to reduce code complexity with Hiera >>

As an update to this article, the original Hiera-eyaml as created by Tom Poulton as well as Hiera-gpg are now in the ownership of Vox. There are benefits to both Hiera-gpg and Hiera-eyaml, which you can explore in this article about why GPG is useful compared to eyamls default.

 🤔 Need extra help? Get Puppet support for Hiera-Eyaml!

How to Set Up Hiera-Eyaml

Setting up hiera-eyaml is not difficult. Simply use the Puppet Forge module to manage your Hiera configuration and set your declaration to manage encryption. Additionally, you can set up both eyaml and gpg eyam, which you can read about here in the Forge. This can be done at the global level and is best for demo/prototypes. For production, you’ll want to configure in the environment layer of Hiera.

On your Puppet server:

class { 'hiera': 
  hiera_version   => '5', 
  hiera5_defaults => { 'datadir' => 'data', 'data_hash' => 'yaml_data' }, 
  hierarchy       => [ 
    'name'        => 'Example yaml', 
    'paths'       => [ 
      'secure.eyaml', 
      'nodes/%{trusted.certname}.yaml', 
      'virtual/%{facts.virtual}.yaml', 
      'os/%{facts.os.family}.yaml', 
      'common.yaml', 
    ], 
    'lookup_key'  => 'eyaml_lookup_key', 
    'options'     => { 
      'pkcs7_private_key' => '/etc/puppetlabs/puppet/keys/private_key.pkcs7.pem', 
      'pkcs7_public_key'  => '/etc/puppetlabs/puppet/keys/public_key.pkcs7.pem', 
    } 
  ], 
  eyaml           => true, 
} 

Note: For Hiera version 5 when calling the class, please remember to pass '5' to 'hiera_version' as in the example above. Also please note that 'hierarchy' is an array of hash in version 5.

When you declare the Hiera-eyaml class on your server, it uses the proper gem provider to install hiera-eyaml (pe_gem for Puppet Enterprise, and gem for Open Source Puppet). It then uses the installed gem to generate a private/public key pair to encrypt and decrypt data.

Additionally, the declaration uses a template to generate a hiera.yaml file that will look something like this:

--- 
version: 5 
 
defaults: 
  datadir: data 
  data_hash: yaml_data 
 
hierarchy: 
  - name: "Example yaml" 
    paths: 
      - "secure.eyaml" 
      - "nodes/%{trusted.certname}.eyaml" 
      - 'virtual/%{facts.virtual}.yaml'  
      - "os/%{facts.os.family}.eyaml" 
      - "common.yaml" 
    lookup_key: eyaml_lookup_key 
 
options: 
  pkcs7_private_key: /etc/puppetlabs/puppet/keys/private_key.pkcs7.pem 
  pkcs7_public_key: /etc/puppetlabs/puppet/keys/public_key.pkcs7.pem 

This example assumes the server is Puppet Enterprise, which stores configuration data in /etc/puppetlabs/puppet. If you are using open source Puppet, the configuration directory will be under /etc/puppet. Using the Hiera module, you can override the values shown if you have configured your server differently than the example above.

In the above example, secure is our hiera-eyaml file, and it is the top of our hierarchy. That’s because you want your secure data settings to be the foremost override level in your hierarchy — secured key variables should be matched first.

How to Edit Files with Hiera-Eyaml

Now you’re set to use Hiera-eyaml. To edit files, you have a few options.

The most obvious option is to log in to the Puppet server and edit the secure.eyaml file directly. Please don’t do this! You should minimize direct access to your server and keep track of your code by using version control to manage your Puppet and Hiera-eyaml files. (And you are, aren’t you?)

The best option is for your Puppet developers to install the hiera-eyaml gem on their local working environments, copy only the public key locally to their hard drives, and configure them using config.yaml:

~/.eyaml/config.yaml 
 
--- 
pkcs7_public_key: '/Users/myuser/keys/eyaml/public_key.pkcs7.pem' 

Once the configuration file and associated key are in the right place, you can directly manage the secure.eyaml file in your VCS repository directory. You can use the eyaml command to input your sensitive data and receive an encrypted block.

$ eyaml encrypt -s 'mystrongpassword' 
[hiera-eyaml-core] Loaded config from /Users/username/.eyaml/config.yaml 
string: ENC[PKCS7,...==] 
  
OR 
  
block: > 
    ENC[PKCS7,...==]

Next, copy and paste the text from after block: to the end of the block into yoursecure.eyaml file as you would any other Hiera-eyaml yaml file.

Here’s the block in the secure.eyaml file:

--- 
mysql::server::root_password:     ENC[PKCS7,...==] 

This will open secure.eyamly using your default editor. The contents will look something like this:

--- 
mysql::server::root_password: > 
    DEC(1)::PKCS7[mystrongpassword]! 

Just edit the text between the brackets, save as you usually would in your default editor, and that’s it! You’re ready to commit the new version to your Puppet repository.

You've Installed Hiera-Eyaml. What Next?

You’ve installed Hiera-eyaml and configured Hiera-eyaml to use it. You’ve got your key management down and have committed your secure.eyaml to your repository. You’ve deployed the latest version to your Puppet server. What happens next?

Puppet will run on the agent and tell the server to compile a catalog as it usually does. However, servers that get the secure information will receive a catalog with decrypted values. This catalog is delivered to the node via SSL, so the information is protected while it is in transit.

How To Bypass Reporting

One thing that may be of some concern to you is that hiera-eyaml changes are reported, which will show up on dashboards like the Puppet Enterprise Console. If you change a password, the diff will show up in reports, including on the console.

Don’t fret, you can still use hiera-eyaml even if your organization needs a higher level of security. You can bypass reporting by setting the show_diff metaparameter to “false” on sensitive resources.

Another solution is to write your own reporting processor to input and parse tags, suppressing reporting on given tags.

And that’s it! Congratulations, you’re now using hiera-eyaml. Your passwords are safe, and you can manage them quickly and easily in Hiera!

Get Started with Puppet Enterprise

Puppet Enterprise can help you easily and securely manage your infrastructure with more automation and less effort. 

If you're ready to add consistency and an extra layer of security through automation and enforcement, Puppet Enterprise can help. 

Ready to get started with a free trial?

Try Puppet Enterprise

Learn More

• Read about secrets management with HashiCorp Vault and Puppet
• Tips on managing compliance drift with Puppet
• How automated configuration management helps with security

Terri Haber is a Professional Services Engineer at Puppet.

This blog was originally published on October 21, 2014, and has since been updated for accuracy and relevance.