- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with the credstash module
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
The credstash module installs [credstash] 1 and surfaces all accessible credstash credentials as a facter fact. The credstash module works on Puppet 3.x/4.x under Debian or RedHat based systems.
The credstash module creates a custom fact containing a hash (or stringified hash in Puppet 3.x) of all stored credentials in a [credstash] 1 credential store. This enables you to access previously stored credentials easily in your puppet manifests.
The credstash module also installs credstash using pip.
- Installs python and python-pip through it's dependence on the [puppet-python] 2 module
- Installs [credstash] 1 using pip
The credstash module reads an optional configuration file located at
/etc/puppet-credstash.yaml
. This configuration file allows you to pass
optional configuration options to credstash. The file is a YAML
hash/dictionary of settings.
As this configuration file is consumed by the credstash module custom fact it must be created before puppet runs, not by puppet.
Override the default credstash
[AWS region] 3
of us-east-1
with this setting
Override the default credstash [DynamoDB] 4 table name of credential-store
with this setting
This list enumerates the [AWS KMS] 5 [Encryption Contexts] 6 to use when
fetching credentials. Each Encryption Context is in the form of key=value
region: us-west-2
table: credentials
context:
- environment=prod
- app_tier=web
- product=MyApp
Include the module [as you would any other] 7.
You can access credstash credentials with the credstash module in three ways. The method you should use depends on your puppet version and settings.
With puppet 3.x, non-string facts, like the $credstash
hash, are [converted to
strings] 8 unless you have configured puppet to not convert facts to strings with the
[stringify_facts
] 9 configuration setting.
This method works with Puppet 3.x and 4.x regardless of settings and is the preferred method to fetch credstash credentials.
To fetch a credential call the get_credential
function
class example(
$app_password = get_credential('app_password'),
$db_password = get_credential('myapp:prod:db:password')
) {
file { '/etc/app.conf':
content => template('example/app.conf.erb'),
}
}
This method works with Puppet 3.x and 4.x regardless of settings.
Every available credstash credential is surfaced in its own facter fact.
The name of the credential is [sanitized] 13 into a valid puppet variable name and
prefixed with credstash_
.
$one = $credstash_app_password # From credstash['app_password']
$two = $credstash_myapp_prod_db_password # From credstash['myapp:prod:db:password']
$three = $credstash_myapp_prod_db_password # From credstash['myapp:prod:db:password']
This method only works with Puppet 4.x or with Puppet 3.x with [stringify_facts
] 9 set to
false
.
class example() {
$app_password = $credstash['app_password']
$db_password = $credstash['myapp:prod:db:password']
file { '/etc/app.conf':
content => template('example/app.conf.erb'),
}
}
Classes:
Facts:
Functions:
Prerequisites:
Installs credstash using pip.
Include the credstash
class to install credstash:
class { 'credstash': }
A Facter fact that contains all of the fetched credentials in the form of a hash of credentials names and secrets (or a stringified hash in Puppet 3.x).
{"app_password" => "s3cret",
"cookie_secret" => "52af5423-3593-4d70-9a98-2ee2e5d9ad08"}
Every credential is surfaced as a Facter fact with a name based on the
credential name. $credstash['example']
would be available as
$credstash_example
. Each credential name is [sanitized] 13 into a valid
puppet variable name and prefixed with credstash_
.
A function which returns a credstash credential value for the name passed to
the function. If the credstash facter fact is a string (due to running under
Puppet 3.x), the string is destringified first into a hash. Next
get_credential
fetches the credential from the hash and finally unescapes
the credential value and returns it.
class example(
$app_password = get_credential('app_password'),
) {
file { '/etc/app.conf':
content => template('example/app.conf.erb'),
}
}
A function which converts a puppet stringified object back into the
structured data object it originated as. destringify
does this by
converting the string into a JSON readable format using regular expressions
and then JSON parsing the resulting string. The object is returned.
class example() {
$credentials = destringify($credstash)
$app_password_escaped = $credentials['app_password']
$app_password = unescape($app_password_escaped)
file { '/etc/app.conf':
content => template('example/app.conf.erb'),
}
}
get_credential
uses destringify
to access
the stringified credstash hash.
A function that converts an escaped string into an unescaped string.
unescape
accepts an escaped string as an argument and returns the unescaped
string.
See the destringify example above.
[credstash] 1 uses either IAM policy permissions or KMS Grants to decrypt the encrypted credentials from the DynamoDB table. Without these permissions, The credstash module will return no credentials as credstash won't have access to any. To learn more about the permissions needed by credstash visit the [credstash site] 1
The credstash module configuration file, /etc/puppet-credstash.yaml
is
optional. If you're using a non-default AWS region or DynamoDB table name you
will need to set this in this configuration file. If you're using Encryption
Contexts to control access to your stored credentials, you will need to set the
contexts in this configuration file.
The credstash module fetches and decrypts credentials. These credentials must have previously been encrypted and uploaded with credstash.
The credstash module has been tested on RedHat based systems and should also work under Debian systems.
Currently, credstash 1.3.1 does not store the encryption contexts used for
encryption when credentials are stored. As a result, in order for
the credstash module to fetch credentials with credstash, that encryption context
must be provided in the credstash module configuration file. Since the
credstash module configuration file must be present before facter runs and
as a result before puppet runs, it would have to be made available by being
burned into the AMI, written by a user_data
driven script or by some other
non-puppet means. This is not ideal. Once credstash supports recording of
encryption contexts, this dependence on a credstash module configuration file
can be removed.
Feel free to [fork this module on github] 12 and contribute. Pull Requests are welcome.