October 21, 2021

How To Use Hiera-Eyaml To Encrypt Your Sensitive Data

How to & Use Cases
Community & Open Source

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.

Table of Contents

What Is Hiera and How Is It Used?

Puppet uses Hiera to store configuration data in key-value pairs and look up what data a particular module needs for a given node during catalog compilation. While Hiera allows for storing sensitive data separately, it cannot ensure that data will be secured.

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.

Related: How to reduce code complexity with Hiera

Get Hiera Support Through Puppet

What Is Hiera-Eyaml?

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

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

How To Set Up Hiera-Eyaml

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 server:

class { 'hiera':
  hierarchy => [
    'secure',
    '%{fqdn}',
    '%{environment}',
    'common'
  ],
  eyaml => true,
}

When you declare the Hiera 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:

backends:
  - yaml
  - eyaml
 
:hierarchy:
  - secure
  - "%{fqdn}"
  - "%{environment}"
  - common
 
:yaml:
  :datadir: '/etc/puppetlabs/puppet/hieradata'
:eyaml:
  :datadir: '/etc/puppetlabs/puppet/hieradata'
  :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.

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'

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

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

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

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:

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

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 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 to easily and securely manage your infrastructure with more automation and less effort. Ready to get started with a free trial?

Try Puppet Enterprise

Learn More

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.