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 Oct 31st 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.6.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.6.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.6.0 Oct 31st 2022

vault_lookup

Build Status Release Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores puppetmodule.info docs Apache-2 License

Module to integrate Puppet 6 (and newer) and Puppet Enterprise 2019 (and newer) 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 or by using the Approle authentication method. 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

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

The vault_lookup function can use 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.

  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.

To use AppRole Authentication

vault_lookup can also use AppRole authentication to authenticate against Vault with a valid role_id and secret_id. See The Approle Vault Documentation for detailed explanations of creating and obtaining the security credentials. You will need the Role ID (non sensitive) and the Secret ID (sensitive!). The Secret ID can be provided as an argument to the vault_lookup function but it is recommended to pass this as an environment variable and not bake this into code.

Example:

# vault read auth/approle/role/puppet/role-id
Key        Value
---        -----
role_id    XXXXX-XXXX-XXX-XX-XXXXXXXXXX

# vault write -f auth/approle/role/puppet/secret-id
Key                   Value
---                   -----
secret_id             YYYYY-YYYY-YYY-YY-YYYYYYYYYYY
secret_id_accessor    ZZZZZ-ZZZZZZ-ZZZZZZ-ZZZZZZZZ-ZZZZ
secret_id_ttl         0s

In order to use the AppRole auth engine you must set the VAULT_AUTH_METHOD environment variable (defaults to cert) to approle

export VAULT_AUTH_METHOD=approle
export VAULT_ROLE_ID=XXXXX-XXXX-XXX-XX-XXXXXXXXXX
export VAULT_SECRET_ID=YYYYY-YYYY-YYY-YY-YYYYYYYYYYY

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