Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

azure_key_vault

The azure_key_vault module allows you to easily fetch secrets securely within your puppet manifests.
Project URLRSS FeedReport issues

355,791 downloads

334 latest version

4.6 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

  • 3.3.0 (latest)
  • 3.2.0
  • 3.1.1
  • 3.1.0
  • 3.0.0
  • 2.1.0
  • 2.0.2
  • 2.0.1
  • 2.0.0
  • 1.1.2
  • 1.1.1
  • 1.1.0
  • 1.0.2
  • 1.0.1
  • 1.0.0
  • 0.4.0
  • 0.3.0
  • 0.2.0
  • 0.1.0
released Apr 29th 2021
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 7.0.0
  • , , , , , ,

Start using this module

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

Add this module to your Puppetfile:

mod 'tragiccode-azure_key_vault', '1.1.2'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add tragiccode-azure_key_vault
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install tragiccode-azure_key_vault --version 1.1.2

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: azure, vault, azure-key-vault, azure-vault

Documentation

tragiccode/azure_key_vault — version 1.1.2 Apr 29th 2021

azure_key_vault

Puppet Forge Version Puppet Forge Pdk Version Puppet Forge Downloads Puppet Forge Endorsement

Table of Contents

  1. Description
  2. Setup
  3. How it works
  4. How it's secure by default
  5. Usage
  6. Reference - An under-the-hood peek at what the module is doing and how
  7. Development - Guide for contributing to the module

Description

Secure secrets management is essential and critical in order to protect data in the cloud. Key Vault is Microsoft Azure's solution to make this happen. This module provides a Puppet function and a Hiera backend that allows you to easily fetch secrets securely on the puppet server and embed them into catalogs during compilation time.

Setup

The module requires the following:

How the function works

This module contains a Puppet 4 function that allows you to securely retrieve secrets from Azure Key Vault. In order to get started simply call the function in your manifests passing in the required parameters:

$important_secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

This example fetches the latest secret with the name "important-secret" from the vault named "production-vault". Under the covers it calls the Azure instance metadata service api to get an access token in order to make authenticated requests to the vault api on-behalf-of the MSI. Once the secret is returned you can begin to use it throughout your puppet code.

NOTE: In order to improve performance and avoid the request limit for the metadata service api the api token retrieved once then stored in a cache that exists for the duration of the puppet run.

In the above example the api_versions hash is important. It is pinning both of the Azure specific api's ( instance metadata api & vault api ) used under the hood to specific versions so that you have full control as to when your puppet code starts calling newer/older versions of the apis. In order to understand what versions are available to your regions please visit the azure documentation

How the hiera backend works

This module contains a Hiera 5 backend that allows you to securely retrieve secrets from Azure key vault and use them in hiera.

Add a new entry to the hierarchy hash in hiera.yaml referencing the vault name and API versions:

- name: 'Azure Key Vault Secrets'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: production-vault
      vault_api_version: '2016-10-01'
      metadata_api_version: '2018-04-02'
      key_replacement_token: '-'

To retrieve a secret in puppet code you can use the lookup function:

notify { 'lookup':
  message => lookup('important-secret'),
}

This function can also be used in hiera files, for example to set class parameters:

some_class::password: "%{lookup('important-secret')}"

You can use a fact to specify different vaults for different groups of nodes. It is recommended to use a trusted fact such as trusted.extensions.pp_environment as these facts cannot be altered. Alternatively a custom trusted fact can be included in the certificate request

- name: 'Azure Key Vault Secrets from trusted fact'
    lookup_key: azure_key_vault::lookup
    options:
      vault_name: "%{trusted.extensions.pp_environment}"
      vault_api_version: '2016-10-01'
      metadata_api_version: '2018-04-02'
      key_replacement_token: '-'

A note on secret keys

KeyVault secret names can only contain the characters 0-9, a-z, A-Z, and -.

When relying on automatic parameter lookup, this is almost always going to contain the module delimiter (::) or underscores.

This module will automatically convert the variable name to a valid value by replacing every invalid character with the key_replacement_token value, which defaults to -.

For example, the hiera variable puppetdb::master::config::puppetdb_server will automatically be converted to puppetdb--master--config--puppetdb-server before being queried up in KeyVault.

When troubleshooting, you can run hiera from the commandline with the --explain option to see the key name being used :

  Using normalized KeyVault secret key for lookup: puppetdb--master--config--puppetdb-server

How it's secure by default

In order to prevent accidental leakage of your secrets throughout all of the locations puppet stores information the returned value of the azure_key_vault::secret function & Hiera backend return a string wrapped in a Sensitive data type. Lets look at an example of what this means and why it's important. Below is an example of pulling a secret and trying to output the value in a notice function.

$secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})
notice($secret)

This outputs Notice: Scope(Class[main]): Sensitive [value redacted]

However, Sometimes you need to unwrap the secret to get to the original data. This is typically needed under the following but not limited to circumstances.

  1. You need to programatically change/alter/append to the secret that was retrieved.
  2. The resource you are passing the secret to does not natively handle the Sensitive data type.

These 2 special cases are discussed in detail next.

Special Case 1 - Programatically Changing/Altering/Appending to a secret

In order to change the original secret you always follow the same 3 step process.

  1. unwrap
  2. alter/change
  3. rewrap
$secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

$rewraped_secret = Sensitive("password: ${secret.unwrap}")

file { 'C:\\DataForApplication.secret':
  content   => $rewraped_secret,
  ensure    => file,
}

Special Case 2 - A Resource doesn't natively support Puppet's Sensitive Data type

Unfortunately, All resource's don't magically handle the sensitive data type. In order to know if a resource supports it or not simply read the documentation or browse through the code if it's available. If you are using a resource that doesn't support the sensitive data type you can unwrap the secret but but you are no longer guaranteed the secret will not get leaked in logs/reports depending on what the resource does with the secret you passed to it. Below is an example of an imaginary resource that doesn't support the sensitive data type and how you can unwrap to handle this situation.

$admin_password_secret = azure_key_vault::secret('production-vault', 'important-secret', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
})

resource_not_supporting_sensitive { 'my_resource':
    username => 'admin',
    password => $admin_password_secret.unwrap,
}

NOTE: Whatever resource you run into that doesn't support the sensitive data type you should open a issue/ticket with the person/organization maintaining the resource.

Usage

Embedding a secret in a file

Below shows an example of how to retrieve a secret and place it in a file on a node. This is typically done because some application/process is expecting the file to exist with the secret in order to get some work done ( such as connecting to a database ).

file { 'C:\\DataForApplication.secret':
  content   => azure_key_vault::secret('production-vault', 'important-secret', {
    metadata_api_version => '2018-04-02',
    vault_api_version    => '2016-10-01',
  }),
  ensure    => file,
}

Retrieving a specific version of a secret

By Default, the latest secret is always retrieved from the vault. If you want to ensure only a specific version of a secret is retrieved simply pass a parameter to specify the exact version you want.

$admin_password_secret = azure_key_vault::secret('production-vault', 'admin-password', {
  metadata_api_version => '2018-04-02',
  vault_api_version    => '2016-10-01',
},
'067e89990f0a4a50a7bd854b40a56089')

NOTE: Retrieving a specific version of a secret is currently not available via the hiera backend

Reference

See REFERENCE.md

Development

Contributing

  1. Fork it ( https://github.com/tragiccode/tragiccode-azure_key_vault/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request