Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

credstash

Module to deploy credstash and create custom facts
Project URLRSS FeedReport issues

30,863 downloads

147 latest version

3.1 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.0.1 (latest)
  • 1.0.0
  • 0.6.4
  • 0.6.3
  • 0.6.2
  • 0.6.1
  • 0.6.0
  • 0.5.0
released Apr 27th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2021.7.x
  • Puppet >= 7.24 < 9.0.0

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'gene1wood-credstash', '1.0.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add gene1wood-credstash
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install gene1wood-credstash --version 1.0.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: security, ec2, aws, secrets, credstash

Documentation

gene1wood/credstash — version 1.0.1 Apr 27th 2024

credstash

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with the credstash module
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module

Overview

The credstash module installs credstash 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.

Module Description

The credstash module creates a custom fact containing a hash (or stringified hash in Puppet 3.x) of all stored credentials in a credstash credential store. This enables you to access previously stored credentials easily in your puppet manifests.

The credstash module also installs credstash using pip.

Setup

What the credstash module affects

  • Installs python and python-pip through it's dependence on the puppet-python module
  • Installs credstash using pip

Setup Requirements

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.

region

Override the default credstash AWS region of us-east-1 with this setting

table

Override the default credstash DynamoDB table name of credential-store with this setting

context

This list enumerates the AWS KMS Encryption Contexts to use when fetching credentials. Each Encryption Context is in the form of key=value

Example /etc/puppet-credstash.yaml

    region: us-west-2
    table: credentials
    context:
    - environment=prod
    - app_tier=web
    - product=MyApp

Beginning with the credstash module

Include the module as you would any other.

Usage

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 unless you have configured puppet to not convert facts to strings with the stringify_facts configuration setting.

get_credential function

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'),
    }
  }

Individual credstash facts

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 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']

credstash fact

This method only works with Puppet 4.x or with Puppet 3.x with stringify_facts 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'),
    }
  }

Reference

Classes:

Facts:

Functions:

Prerequisites:

Class: credstash

Installs credstash using pip.

Include the credstash class to install credstash:

  class { 'credstash': }

Fact: 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"}

Fact: credstash_example

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 into a valid puppet variable name and prefixed with credstash_.

Function: get_credential

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'),
    }
  }

Function: destringify

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.

Function: unescape

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.

Prerequisite: AWS state

credstash 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

Prerequisite: Configuration file

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.

Prerequisite: Stored credentials

The credstash module fetches and decrypts credentials. These credentials must have previously been encrypted and uploaded with credstash.

Limitations

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.

Development

Feel free to fork this module on github and contribute. Pull Requests are welcome.