Encrypt Your Data Using Hiera-Eyaml

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 lets you write and use reusable manifests and modules. You store your organization-specific data in Hiera, 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, but how.

In the past, the de facto way to store sensitive data in Hiera was to use hiera-gpg. However, with hiera-gpg, the entire Hiera data file had to be encrypted. Recognizing that managing this kind of file over the long term would be a burden, Tom Poulton created hiera-eyaml. This enables Hiera users to encrypt data blocks within the eyaml file separately, making management much easier. (Editor's Note: eyaml is not a commercially supported backend for Puppet Enterprise.)

The setup

Setting up hiera-eyaml is not difficult. Simply use the Puppet Forge module puppet-hiera to manage your Hiera configuration and set your declaration to manage encryption. On your Puppet master:

When you declare the Hiera class on your master, 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:

This example assumes the master 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 master 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.

The default file extension for the secure Hiera file is eyaml. However, if you want to use yaml, simply add the following line to your hiera.yaml, under the :eyaml: section:

:extension: ‘yaml’

Editing files

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 master and edit the secure.eyaml file directly. Please don’t do this! You should minimize direct access to your master and keep track of your code by using version control to manage your Puppet and Hiera 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.

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 yaml file.

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

Now that you have added a block to the secure.eyaml file, you can edit and change the password at any time.

eyaml edit secure.eyaml

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

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.

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.

Behind the scenes

You’ve installed hiera-eyaml and configured Hiera 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 master. What happens next?

Puppet will run on the agent and tell the master 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.

Gotcha!

One thing that may be of some concern to you Puppetmasters out there is that hiera-eyaml changes are reported on, 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!

Terri Haber is a professional services engineer at Puppet Labs.

Learn More

• How to debug Hiera.
• Are you a pouncer or a stalker? Either way, here are some resources for learning Hiera.
• You can use Hiera to keep your data separate from you Puppet code.
• Hiera-eyaml enables Hiera users to encrypt data blocks within the eyaml file separately, making management much easier.
• If you’re not already using Puppet Enterprise, download and try it out for free on 10 nodes.