Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

vault_lookup

Secret retrieval from Vault
Project URLRSS FeedReport issues

28,256 downloads

2,861 latest version

5.0 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.1.0 (latest)
  • 1.0.0
  • 0.7.0
  • 0.6.0
  • 0.5.0
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.1
released Jun 30th 2022
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x
  • Puppet >= 6.16.0 < 8.0.0
  • , , , , , , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'puppet-vault_lookup', '0.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppet-vault_lookup
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppet-vault_lookup --version 0.3.0

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

Documentation

puppet/vault_lookup — version 0.3.0 Jun 30th 2022

vault_lookup

Module to integrate Puppet 6 and Puppet Enterprise 2019 agents with Hashicorp Vault.

Table of Contents

  1. Description
  2. Setup - The basics of getting started with vault_lookup
  3. Usage - Configuration options and additional functionality

Description

For users with a Puppet Enterprise 2019 or open source Puppet 6 infrastructure wanting to leverage secrets from an existing Hashicorp Vault server. Used with Puppet 6's Deferred type, this allows agents to retrieve secrets from Vault when a catalog is applied. In this way, the secret data is not embedded in the catalog and the master never sees it. See this blog post for more information and other secret store integrations.

Authentication with Vault is achieved via Puppet certificates. See the Vault documentation for more information on setting up finer grained access controls.

Requirements

This is expected to be run using the Deferred type, which requires Puppet 6.0.0 or later, and of course Vault to store the data.

Setup

The vault_lookup function uses the Puppet agent's certificates in order to authenticate to the Vault server; this means that before any agents contact a Vault server, you must configure the Vault server with the Puppet Server's CA certificate, and Vault must be part of the same certificate infrastructure.

To set up Vault to use the Puppet Server CA cert:

  1. Set up Vault using Puppet certs (if not already set up this way) If the Vault host has a Puppet agent on it then you can just use the existing certificates. Otherwise generate a new certificate with puppetserver ca and copy the files.
puppetserver ca generate --certname my-vault.my-domain.me

In the Vault listener configuration, set tls_client_ca_file as the Puppet CA cert, tls_cert_file as the agent or generated certificate, and tls_key_file as the agent or generated private key.

  1. Enable cert auth for Vault Hashicorp’s Vault supports a variety of auth methods that are listed in their documentation; the auth method required for usage with the vault_lookup function is named cert, and can be turned on with the Vault CLI:
$ vault auth enable cert
  1. Upload the Puppet Server CA certificate to Vault. After cert auth has been enabled for Vault, upload the CA certificate from your Puppet Server to Vault and add it as a trusted certificate.
$ vault write auth/cert/certs/puppetserver \
    display_name=puppet \
    policies=prod,test \
    certificate=@/path/to/puppetserver/ca.pem \
    ttl=3600

Once the certificate has been uploaded, any Puppet agent with a signed certificate will be able to authenticate with Vault.

Usage

Install this module as you would in any other; the necessary code will be distributed to Puppet agents via pluginsync.

In your manifests, call the vault_lookup::lookup function using the Deferred type. For example:

$d = Deferred('vault_lookup::lookup', ["secret/test", 'https://vault.hostname:8200'])

node default {
  notify { example :
    message => $d
  }
}

The lookup function will be run on the agent and the value of $d will be resolved when the catalog is applied. This will make a call to https://vault.hostname:8200/v1/secret/test and wrap the result in Puppet's Sensitive type, which prevents the value from being logged.

You can also choose not to specify the Vault URL, and then Puppet will use the VAULT_ADDR environment variable. This will be either set on the command line, or set in the service config file for Puppet, on Debian /etc/default/puppet, on RedHat /etc/sysconfig/puppet:

$d = Deferred('vault_lookup::lookup', ["secret/test"])

node default {
  notify { example :
    message => $d
  }
}