Skip to main content

Hashicorp Vault - Key Storage Plugin

Hashicorp Vault - Key Storage Plugin

Hashicorp Vaultopen in new window is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, or certificates. Vault provides a unified interface to any secret, while providing tight access control and recording a detailed audit log.

Rundeck offers a Key Storage Backendopen in new window plugin for storing Key Store data in Vaultopen in new window and has been verified to work with HCP Vault.

A more detailed installation How Toopen in new window is available in our learning section.

This plugin is bundled with the Enterprise version. No installation steps required.


Quick Start

Example configuration using the System Configuration module:

Vault Storage Config
Vault Storage Config
Vault Storage Config
Vault Storage Config
Vault Storage Config
Vault Storage Config
Vault Storage Config
Vault Storage Config

Settings Descriptions

Add the settings to the System Configuration module (3.4.0+ Enterprise) or $RDECK_BASE/etc/

Note: These settings will require a restart of Rundeck to take effect.

  • prefix: Vault Prefix in Vault secret backend[index].config.prefix=rundeck
  • address: Vault Address of the Vault server[index].config.address=https://vaultURL:8200
  • authBackend: Vault Authentication backend[index].config.authBackend=authBackend

Default value: token

Allowed values: approle, cert, github, token, userpass

  • token: Vault authentication token. Required, if authentication backend is 'token'[index].config.token=xxxxxx
  • username: User name. Required for user/password and LDAP authentication backend[index].config.username=username
  • password: Password. Required for user/password and LDAP authentication backend[index].config.password=password
  • approleId: AppRole role ID. The role-id used for authentication[index].config.approleId=approleId
  • approleSecretId: AppRole secret ID. The secret-id used for authentication[index].config.approleSecretId=approleSecretId
  • approleAuthMount: AppRole mount name. The mount name of the AppRole authentication back end[index].config.approleAuthMount=approleAuthMount
  • githubToken: GitHub token. The app-id used for authentication[index].config.githubToken=githubToken
  • keyStoreFile: Key store file A Java keystore, containing a client certificate that's registered with Vault's TLS Certificate auth backend.[index].config.keyStoreFile=/path/keyfile
  • keyStoreFilePassword: Key store password The password needed to access the keystore[index].config.keyStoreFilePassword=/path/keyStoreFilePassword
  • trustStoreFile: Truststore file. A JKS truststore file, containing the Vault server's X509 certificate[index].config.trustStoreFile=/path/trustStoreFile
  • pemFile: PEM file. The path of a file containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.[index].config.pemFile=/path/pemFile
  • clientPemFile: Client PEM file. The path of a file containing an X.509 certificate, in unencrypted PEM format with UTF-8 encoding.[index].config.clientPemFile=/path/clientPemFile
  • clientKeyPemFile: Client key PEM file. The path of a file containing an RSA private key, in unencrypted PEM format with UTF-8 encoding.[index].config.clientKeyPemFile=/path/clientKeyPemFile
  • namespace: Define the Hashicorp namespace for the integration. If root is needed leave blank or set to root/[index].config.namespace=hashicorpNamespace
  • authNamespace: When using Namespaces if the user or AppRole is in a different namespace than the password entries use this to set the namespace where Authentication should take place. If left blank the namespace entry from above will be used (if set). To use the root namespace set to root/.[index].config.authNamespace=namespace_for_auth
  • validateSsl: Enable/Disable SSL validation. Specifies whether SSL validation is to be performed[index].config.validateSsl=true/false

Default value: true

  • maxRetries: Max retries. Maximum number of connection retries to Vault server[index].config.maxRetries=5

Default value: 5

  • retryIntervalMilliseconds: Retry interval. Connection retry interval, ms[index].config.retryIntervalMilliseconds=1000

Default value: 1000

  • openTimeout: Open timeout. Connection opening timeout, ms[index].config.openTimeout=5

Default value: 5

  • readTimeout: Read timeout. Response read timeout, ms[index].config.readTimeout=20

Default value: 20

  • secretBackend: Secret Backend. The secret backend to use in vault[index].config.secretBackend=secret

Default value: secret

  • storageBehaviour: Storage Behaviour. Use the default Rundeck Behaviour for key storage (with rundeck headers) or use just the key/value behaviour from vault. Options are: rundeck, vault[index].config.storageBehaviour=vault/rundeck

Default value: rundeck

  • engineVersion: Vault Engine Version Key/Value Secret Engine Config[index].config.engineVersion=1/2

Default value: 1

  • removePathPrefix: Remove Rundeck's prefix path (keys/...) in Vault's items path[index].removePathPrefix=true

Default value: false

More Configuration Examples

example basic settings$VAULT_URL$VAULT_TOKEN

existing vault storage

For existing vault storage, probably you will need to remove the default keys path added by default for rundeck. You can use these settings for an existing vault storage:$VAULT_URL$VAULT_TOKEN

Using APPROLE authentication and Namespaces

You can use these settings for an existing vault storage:$VAULT_URL



Vault API versions

Since version 1.3.1, this plugin can work with kV Secrets Engine - Version 2. A new config variable was added in order to set the API version that you need to use:

  • engineVersion=1 will work with vault version 0.x
  • engineVersion=2 will work with vault version 1.x


By default, the value is set to v1 (1)

Also note that V2 of the kV Secrets Engineopen in new window requires updates/changes to any policies you might be using to limit access.

If access is limited to a specific subfolder the following example policy can be used to confirm you have given the proper access for Rundeck to manage the keys.

path "secret_v2/data/your/path/here/*" {
    capabilities = ["create", "read", "update"]

path "secret_v2/metadata/your/path/here/*" {
    capabilities = ["read", "delete", "list"]

path "secret_v2/delete/your/path/here/*" {
    capabilities = ["update"]

Minimal version requirements

  • Rundeck 3.3.0
  • Vault 0.9.0