Rundeck integration with Vault

Hey there!
Integrating HashiCorp Vault is a great way to secure your environment, but short token lifespans and engine versions can definitely cause some friction. Here is what is causing those issues and how to fix them:
1. The KV Engine V2 Issue
The engineVersion=2 parameter is correct, but it relies heavily on matching your exact Vault path layout. If Vault is rejecting it and reverting to V1, check your secretBackend property. For KV V2, Vault appends a /data/ string into the API path. Ensure your configuration exactly mirrors the Rundeck HashiCorp Vault Key Storage Documentation syntax.
2. Token Expiration & Job Failures (Why it Breaks)
Using a raw Vault token with a 5-minute expiry (authBackend=token) will inevitably break your cluster. Rundeck's storage plugin does not natively refresh or request a new raw token when it expires. Once that 5-minute window closes, Rundeck loses its pathing to the entire storage tree. Even jobs that don't explicitly use keys will fail because Rundeck can no longer look up node execution credentials or global system configurations stored in the backend hierarchy.
3. The Fix: Switch to AppRole
Instead of static tokens, you should use Vault's AppRole authentication method. AppRole allows Rundeck to automatically authenticate, request its own tokens, and natively manage lifecycle refreshes without breaking connections.
Update your rundeck-config.properties block to use AppRole parameters:

rundeck.storage.provider.1.config.authBackend=approle
rundeck.storage.provider.1.config.approleId=YOUR_APPROLE_ID
rundeck.storage.provider.1.config.approleSecretId=YOUR_SECRET_ID

You can follow our step-by-step How-To Integrate HashiCorp Vault Guide to generate the AppRole credentials inside Vault and apply them cleanly to your Rundeck instance.
Let us know if migrating to AppRole stabilizes your job runs!

Below are the all parameters that are already added to rundeck config file, as part of setting up vault.
 

rundeck.storage.provider.1.type=vault-storage
rundeck.storage.provider.1.path=keys
rundeck.storage.provider.1.removePathPrefix=true

rundeck.storage.provider.1.config.address=<link to vault> 
rundeck.storage.provider.1.config.authBackend=approle
rundeck.storage.provider.1.config.approleId=1234-4567-890. #changed actual value for reference
rundeck.storage.provider.1.config.approleSecretId=4567-1234-489123-6789  #changed actual value for reference
rundeck.storage.provider.1.config.approleAuthMount=approle

rundeck.storage.provider.1.config.secretBackend=testv1
rundeck.storage.provider.1.config.engineVersion=2
rundeck.storage.provider.1.config.storageBehaviour=vault
rundeck.storage.provider.1.config.prefix=rundeck

We are not using authBackend=token anywhere directly, even with above configs rundeck is not requesting its own tokens after the first restart, nor managing lifecycle refreshes without breaking connections.

Please check and let me know, if any changes needs to be done. 

Thanks in advance.

Hi, you can test some retry/maxretry/timeout params as follows (this is from my test environment):

rundeck.storage.provider.1.type=vault-storage
rundeck.storage.provider.1.path=keys
rundeck.storage.provider.1.removePathPrefix=false
rundeck.storage.provider.1.config.secretBackend=secret
rundeck.storage.provider.1.config.prefix=rundeck
rundeck.storage.provider.1.config.address=http://myvault:8200
rundeck.storage.provider.1.config.token=token
rundeck.storage.provider.1.config.storageBehaviour=vault
rundeck.storage.provider.1.config.maxRetries=3
rundeck.storage.provider.1.config.retryIntervalMilliseconds=100
rundeck.storage.provider.1.config.openTimeout=3
rundeck.storage.provider.1.config.readTimeout=5
rundeck.storage.provider.1.config.engineVersion=2
rundeck.storage.converter.1.type=jasypt-encryption
rundeck.storage.converter.1.path=keys/
rundeck.storage.converter.1.config.encryptorType=custom
rundeck.storage.converter.1.config.password=rundeck
rundeck.storage.converter.1.config.algorithm=PBEWITHSHA256AND128BITAES-CBC-BC
rundeck.storage.converter.1.config.provider=BC

Hope it helps!

I will add these which will be helpful to communicate with vault, but I don’t think it will be helpful with token expiry.

rundeck.storage.provider.1.config.maxRetries=3
rundeck.storage.provider.1.config.retryIntervalMilliseconds=100
rundeck.storage.provider.1.config.openTimeout=3
rundeck.storage.provider.1.config.readTimeout=5

below is the case i am facing

Rundeck restart
  ↓
Vault plugin logs in using AppRole
  ↓
Vault returns a client token
  ↓
Plugin keeps that Vault client/token in memory
  ↓
Jobs read keys/rundeck using that same token
  ↓
Token expires or client becomes stale
  ↓
Rundeck cannot read Vault key
  ↓
Jobs fail
  ↓
Rundeck restart gets a fresh token

Probably that deserves an Enhacement Request, let me double check.

Ok, regarding the second issue (KV Engine V2 not respected), Plugin 1.2 has a known bug where engineVersion=2 is parsed but the path rewriting (adding /data/ into the URL for V2's API structure) doesn't apply correctly. Please use the latest version available in the Github Repo (https://github.com/rundeck-plugins/vault-storage/releases).

Regarding the third issue (Token expiry with no auto-renewal): this was asked here: https://github.com/rundeck-plugins/vault-storage/issues/24 please add your use case there.

Thanks.

I did try downloading the plugin and installing it, but rundek is not recognizing it, rundeck is recognizing only the plugin that got installed from Rundeck UI → settings → plugins

i will try again now and update if it works

You can use this url to upload the plugin via GUI: https://github.com/rundeck-plugins/vault-storage/releases/download/2.0.1/vault-storage-2.0.1.jar

I installed the new plugin using the link provided from rundeck UI and it is now connecting to Vault. 

in Vault mount testv2 is created → rundeck/keys → under this path we will see keys and values 

do i need to make any changes to “rundeck.storage.provider.1.config.secretBackend=testv2” ? in rundeck i am not seeing errors, and seeing only keys/keys under key storage and not showing keys created in vault. 

This issue is fixed. 

Only issue seen
when user id and password is created from rundeck UI to store in Vault using key type as password, it is getting password stored in a different format with special characters and when called in a job, it is using the same format with special characters. 
 

Ex: if i create user ‘test’ with password ‘test123’ from rundeck UI, it is storing password as “

H�d�BV��>(�ʡ�.W���V�٨���” 

Work around is, login to vault and correct the password. 
 

In Rundeck version 5.10.0, I installed the Vault plugin by navigating to:

**Rundeck UI → Settings → Plugins → Find Plugins → Vault → Install**

I then uploaded Vault Storage Plugin version 2.0.1 from UI

https://github.com/rundeck-plugins/vault-storage/releases/download/2.0.1/vault-storage-2.0.1.jar

logged in to the Rundeck server, I replaced the existing plugin file by renaming the uploaded JAR:

```
mv vault-storage-2.0.1.jar vault-storage.jar
```

The Rundeck UI continued to show the Vault plugin as installed, and the integration worked as expected.

However, when I followed the same process in Rundeck version 5.19.0, it did not work. After running:

```
mv vault-storage-2.0.1.jar vault-storage.jar
```

the Rundeck UI showed that the Vault plugin needed to be installed.

Under **Key Storage**, I also received the following error:

```
Error: Cannot get property 'pluginGroupType' on null object
```

I then tried installing the Vault plugin available through the Rundeck UI. The installation completed without displaying any errors, but Rundeck was not able to read secrets from Vault.

When I tried to create a key in Rundeck Key Storage, I received the following error:

```
Encountered error while writing data to Vault.

Expecting HTTP status 204 or 200, but instead receiving 404.

Response body:
{"request_id":"70a6c418-2a91-1365-f68d-42da4460b70b","lease_id":"","renewable":false,"lease_duration":0,"data":null,"wrap_info":null,"warnings":["Invalid path for a versioned K/V secrets engine. See the API docs for the appropriate API endpoints to use. If using the Vault CLI, use 'vault kv put' for this operation."],"auth":null}
```

Based on this error, it appears that the plugin installed through the Rundeck UI is using a KV version 1 API path instead of the required KV version 2 API path.

Because of this, I cannot use the plugin provided through the Rundeck UI. However, manually uploading Vault Storage Plugin version 2.0.1 causes the plugin registration issue described above.

How can I install and configure Vault Storage Plugin version 2.0.1 correctly in Rundeck 5.19.0 and resolve the following issues?

1. The Rundeck UI shows that the Vault plugin needs to be installed after the JAR file is renamed.
2. Key Storage displays the `pluginGroupType` null-object error.
3. The plugin installed through the Rundeck UI appears to use the incorrect Vault KV API path.

Thanks