Hashicorp Vault: Key-Value Engine

Summary

This module contains actions for:

• Creating Secrets Engines
• Creating Secrets
• Reading Secrets
• Updating Secrets

Supported Versions

This plugin supports Hashicorp Vault Key-Value versions 1 & 2.

Remember

You must have a Hashicorp Vault provisioned as a Vault inside PPA to use this plugin.

Actions

hashicorp_vault.key_value.

create_engine

Create a new secrets engine in a Hashicorp Vault.

Minimum Plugin Version: 3.0.0

Input

• engine: the name of the secrets engine (defaults to ppa)

• reason: task interface audit message (defaults to a message with the engine name)

• vault_name: the Hashicorp Vault name in PPA (only necessary if more than one vault is configured)

• kv_version: the version of the key value engine (defaults to 2)

Output

Nothing is outputted by this action.

Example

Creating a new v2 engine called production_secrets.

- hashicorp_vault.key_value.create_engine:
    engine: production_secrets

hashicorp_vault.key_value.

create_secret

Create a new secret in a Key-Value engine.

Minimum Plugin Version: 3.0.0

Input

• secret: the name of the new secret

• data: a dictionary containing keys & values to create in the secret

• engine: the name of the secrets engine (defaults to ppa)

• reason: task interface audit message (defaults to a message with the secret & engine names)

• vault_name: the Hashicorp Vault name in PPA (only necessary if more than one vault is configured)

• kv_version: the version of the key value engine (defaults to 2)

• overwrite: set to true to overwrite any existing secret with the same name (defaults to false)

Output

Nothing is outputted by this action.

Example

Creating a new secret with a username & password in the default ppa v2 engine.

- hashicorp_vault.key_value.create_secret:
    secret: my_new_secret
    data:
      username: "{{ secret_username }}"
      password: "{{ secret_password }}"

hashicorp_vault.key_value.

read_secret

Read all values from a secret in a Key-Value engine.

If you know which keys you need, consider using read_secret_keys instead.

Unlike read_secret_keys, this action will not:

• Start a config wizard if configuration is missing
• Perform any checks on the keys read from the secret

Minimum Plugin Version: 3.0.0

Input

• engine: the name of the secrets engine (defaults to ppa)

• secret: the name of the secret in the secrets engine

• reason: task interface audit message (defaults to a message with the secret name)

• vault_name: the Hashicorp Vault name in PPA (only necessary if more than one vault is configured)

• kv_version: the version of the key value engine (defaults to 2)

Output

A dictionary containing all keys & values from the secret.

Example

• Getting all keys from the active_directory secret in the production engine

• Saving them as a new variable called active_directory_secrets

- hashicorp_vault.key_value.read_secret:
    secret: active_directory
    engine: production
  save: active_directory_secrets

hashicorp_vault.key_value.

read_secret_keys

Read specific values from a secret in a Key-Value engine.

Minimum Plugin Version: 5.0.0

Vault Setup Wizard

PPA can help the Task Operator create any missing engine, secret, or keys supplied to this action.

If create_missing is true & required configuration is missing, the setup wizard will run.

The create_missing input defaults to false for security reasons.

Input

• engine: the name of the secrets engine (defaults to ppa)

• secret: the name of the secret in the secrets engine

• keys: a list of VaultKey dictionaries defining what to retrieve from the secret

• reason: task interface audit message (defaults to a message with the secret name & number of keys)

• vault_name: the Hashicorp Vault name in PPA (only necessary if more than one vault is configured)

• kv_version: the version of the key value engine (defaults to 2)

• create_missing: if true the Vault setup wizard will start if any configuration is missing (defaults to false)

Output

A dictionary containing the keys & values from the secret.

Active Directory

Retrieving 4 keys from the active_directory secret & saving them as domain_controller.

If any keys are missing:

• The Vault Setup Wizard will allow the user to supply them

• The password key is marked as sensitive & will be obfuscated when supplied

  - hashicorp_vault.key_value.read_secret_keys:
      secret: active_directory
      keys:
        - name: address
        - name: domain
        - name: username
        - name: password
          sensitive: true
      reason: Getting Active Directory details
      create_missing: true
    save: domain_controller

SSH With Private Key

Retrieving 5 keys from the ssh secret & saving them as ssh_server.

If any keys are missing:

• The Vault Setup Wizard will allow the user to supply them

• The private_key is marked as both sensitive & as a file, & any uploaded file contents will be obfuscated

• The key_passphrase is marked as sensitive & will be obfuscated when supplied

  - hashicorp_vault.key_value.read_secret_keys:
      secret: ssh
      keys:
        - name: address
        - name: port
        - name: username
        - name: private_key
          format: file
          sensitive: true
        - name: key_passphrase
          sensitive: true
      reason: Getting SSH Server Details
      create_missing: true
    save: ssh_server

hashicorp_vault.key_value.

update_secret

Update the values of a secret in a Key-Value engine.

This action can be used to:

• Replace values in a secret
• Append new values to a secret

This action cannot create a new secret, use create_secret to do this.

Minimum Plugin Version: 2.0.0

Input

• engine: the name of the secrets engine (defaults to ppa)

• secret: the name of the secret in the secrets engine

• data: a dictionary containing keys & values to update in the secret

• reason: task interface audit message (defaults to a message with the secret name)

• vault_name: the Hashicorp Vault name in PPA (only necessary if more than one vault is configured)

• kv_version: the version of the key value engine (defaults to 2)

Output

Nothing is outputted by this action.

Example

Updating the service_now secret's access_token value in the production engine.

- hashicorp_vault.key_value.update_secret:
    secret: service_now
    engine: production
  load:
    data:
      access_token: new_access_token