ReleaseEngineering/PuppetAgain/Secrets

In PuppetAgain, secrets are stored in Hiera.

Usage

To use a secret:

in manifests

class foo {
  if (secret('builder_password') == "")
     fail("missing password")
  }
}

If you need to interpolate the value into a string, you'll need to use a class-local variable.

in templates

This is a little verbose:

 <%= scope.function_secret(['signing_server_username']) %>

do not forget the [..] -- they are optional in puppet-2.7.x, but mandatory in 3.2.x.

Secrets Have Aspects

The secret() function will look for aspect-specific passwords for each aspect of the current host, using a suffix. For example, if a host has aspects "loaner" and "staging", then secret('root_password') will look for the following in hiera, using the first it finds:

 root_password!loaner
 root_password!staging
 root_password 

This is most useful around the 'staging' aspect, as it means that passwords for staging instances can be specified easily, with no conditionals in the module implementing the functionality.

Using EYAML

Secrets are accessed via hiera, using hiera-eyaml. That means that the secrets files are regular YAML files, but contain ciphertext enclosed by ENC[..] where secrets are protected. The public and private keys used for this encryption are stored on the puppetmasters themselves.

Encrypt strings (like passwords)

As root on any puppetmaster, use:

 eyaml encrypt --pkcs7-private-key /etc/hiera/keys/private_key.pem --pkcs7-public-key /etc/hiera/keys/public_key.pem \
    --output examples --password -l 'foo'

where 'foo' is the name of the variable to set. It will prompt for the password to encrypt. The output will go to stdout, in 2 formats (all one line, multiline). Copy/paste whichever result format you prefer into `/etc/hiera/secrets.eyaml` or into your own `/etc/hiera/environments/<username>_secrets.eyaml`.

Encrypt files (e.g. private keys)

Pipe the contents of the file to the above command, and replace --password with --stdin, e.g.

 cat secret_file | eyaml encrypt --pkcs7-private-key /etc/hiera/keys/private_key.pem --pkcs7-public-key /etc/hiera/keys/public_key.pem \
    --output examples --stdin -l 'foo'

and update `/etc/hiera/secrets.eyaml` accordingly as per instructions above.

Check your YAML files

YAML Syntax

Double-check your work before saving -- if this file can't be parsed as valid yaml, all puppet runs will fail. A python one line syntax checker is:

 python -c "import yaml; f=open('secrets.eyaml','r'); yaml.load(f)" && echo "pass" || echo "FAIL"

When in doubt, run `eyaml --help` or `eyaml encrpyt --help`.

Secret values

To check the value of a secret, use 'hiera':

 hiera root_pw_saltedsha512

To check the value of a secret in `/etc/hiera/environments/<username>_secrets.eyaml`, use:

 hiera root_pw_saltedsha512 environment='<username>'

Help! secret() does not interpret my secret

Sometimes, secret() (or function_secret()) may return the raw value, instead of the decrypted one. This is very likely because of a bad copy and paste. In order to verify this, run the hiera command detailed in the section above. If the non-decrypted value is still returned, paste the encrypted value again. Some characters (like the closing ]) may be missing.

User Environments

User environments use the same set of secrets as the production environment, so unless you are adding or modifying secrets, there's no need to mess with them.

Hiera also consults /etc/hiera/environments/$environment_secrets.eyaml, so if you *do* need to add or modify secrets, you can do so there and avoid modifying the production secrets file. Note that environment secrets are not synced from master to master.

Secrets

Many secrets are documented in the modules that use them.

google_api_key

This is the Google API key; see bug 913041.

network_regexps

a list of regular expressions representing the trusted network containing all puppet nodes. This is used, among other things, by the deployment CGI to limit access to known subnets.

mozilla_api_key

This is the Mozilla API key; see bug 1003623.

google_oauth_api_key

This is the google oauth API key; see bug 1075675.

crash_stats_api_token

This is the token for uploading to crash-stats; bug 1119238

adjust_sdk_token

This is the token for the Adjust SDK, used for tracking Fennec installations; bug 1152871

release s3 credentials

boto config for doing release tasks; bug 1213790

Related HOW TO's

• How To: Add new secrets
• How To: Change Secrets