Enable the kv-v2 secrets engine

This page explains how to enable and configure the HashiCorp Vault kv-v2 secrets engine so that Vault can manage and share secrets securely with Itential Platform.

Itential supports only kv-v2. Itential doesn’t support kv-v1.

About the kv-v2 secrets engine

Key-value version 2 (kv-v2) is a secrets engine that stores arbitrary secrets as key-value pairs and includes built-in versioning.

Benefits of kv-v2

Version control

Maintains a complete history of secret changes.
Lets you retrieve or restore previous versions.
Prevents accidental data loss from overwrites.

Enhanced safety

Supports soft deletes, so you can recover a secret within a retention period.
Supports check-and-set operations, which prevent concurrent update conflicts.
Supports configurable retention policies that control how many versions to keep.

Audit capabilities

Tracks creation time, modification time, and version numbers.
Provides a complete audit trail of secret changes.
Helps you comply with security policies.

HashiCorp recommends kv-v2 for production use. It supersedes kv-v1, which doesn’t support versioning or soft deletes.

How versioning works

Each time you update a secret, kv-v2 creates a new version and keeps the previous versions:

# Create the initial secret (version 1)
vault kv put kv-v2/network/routers password=secret123
# Update the secret (version 2; version 1 still exists)
vault kv put kv-v2/network/routers password=newSecret456
# Retrieve the latest version
vault kv get kv-v2/network/routers
# Retrieve a specific version
vault kv get -version=1 kv-v2/network/routers

API path structure

The kv-v2 API path includes /data/:

http://localhost:8200/v1/kv-v2/data/<secret-path>

The /data/ segment distinguishes secret data from metadata and configuration endpoints. You also include this segment when you configure Platform.

Enable the kv-v2 secrets engine

Enable the engine

Run the following command to enable the kv-v2 secrets engine:

vault secrets enable kv-v2

Update the properties file

Go to /opt/pronghorn/current and edit the properties.json file to add the location of the token.txt file. For details, see Configure Vault properties.

Configure Vault properties

To use Vault, add a vaultProps section to your properties.json file.

Configuration parameters

Property	Required	Default	Description
`url`	Yes	`http://localhost:8200`	The URL of the Vault server, including the hostname and port.
`token`	Yes	`/file/path/token.txt`	The path to a file that contains the authentication token.
`endpoint`	Yes	`secret/data`	The endpoint for the secrets engine type.
`readOnly`	Yes	`true`	Controls how Platform writes secret data to Vault. Itential strongly recommends read-only access to Vault.
`authMethod`	No	`token`	The authentication method, either `token` or `approle`.
`role_id`	No	`""`	The Vault role ID for AppRole authentication.
`secret_id`	No	`""`	The Vault secret ID for AppRole authentication.

Token authentication

The following example configures token authentication:

"vaultProps": {
  "url": "http://localhost:8200",
  "authMethod": "token",
  "token": "/opt/vault/token.txt",
  "endpoint": "kv-v2/data",
  "readOnly": true
}

The endpoint value kv-v2/data includes the /data path segment that kv-v2 requires to access secret data. This segment distinguishes the endpoint from metadata or configuration endpoints.

If you don’t specify authMethod, Platform uses token authentication. This default maintains compatibility with earlier Platform configurations.

AppRole authentication

The following example configures AppRole authentication:

"vaultProps": {
  "url": "http://localhost:8200",
  "authMethod": "approle",
  "role_id": "cfb83d9f-fd94-e046-71e2-dcd51147288d",
  "secret_id": "68df6e13-02b2-b60d-a39f-f8b879277d48",
  "endpoint": "kv-v2/data",
  "readOnly": true
}

You must set up AppRole authentication and generate the role_id and secret_id separately in Vault. Include valid policies and TTL or usage limits.

Endpoint URL structure

You can customize the endpoint path. In the following example URL, v1 is a hard-coded path segment in Platform:

http://localhost:8200/v1/kv-v2/data

The URL has the following components:

http://localhost:8200: The Vault server address.
/v1: The Vault API version.
/kv-v2: The secrets engine mount point.
/data: The kv-v2 data endpoint. Required to access secret values.

Configure the readOnly property

The readOnly property in vaultProps controls how Platform writes secret data to Vault. The default is true.

When readOnly is true:

UI masking is disabled.
The UI shows secrets in clear text.
Platform ignores custom user decorations.
Platform doesn’t write data to Vault.

If you change readOnly from false to true after you store passwords in Vault, Platform loses access to those passwords. You must set them again manually.

Verify the configuration

After you enable kv-v2 and configure the Vault properties, verify the connection.

Restart Platform

Restart Platform to apply your configuration changes:

sudo systemctl restart itential-platform

Check the Platform logs

Check the Platform logs for Vault messages:

sudo journalctl -u itential-platform -f

Confirm that the logs show successful Vault authentication.

Test secret storage

Create a test secret in Vault and verify that Platform can retrieve it. For instructions, see Create secrets.

Additional resources

Secrets engines in the HashiCorp Vault documentation
KV secrets engine version 2 in the HashiCorp Vault documentation
Secrets engines overview in the HashiCorp Vault documentation

What’s next

Create secrets

Automatic encryption