Enable the kv-v2 secrets engine

You must enable and configure the Hashicorp Vault secrets engine before it can manage and share secrets securely.

About the kv-v2 secrets engine

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

Why use kv-v2

Version control

• Maintains complete history of secret changes
• Allows you to retrieve or restore previous versions
• Prevents accidental data loss from overwrites

Enhanced safety

• Soft deletes allow secret recovery within a retention period
• Check-and-Set operations prevent concurrent update conflicts
• Configurable retention policies control how many versions to keep

Audit capabilities

• Tracks creation time, modification time, and version numbers
• Provides complete audit trail of secret changes
• Enables compliance with security policies

How versioning works

Each time you update a secret, kv-v2 creates a new version while preserving previous versions:

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

API path structure

Kv-v2 uses a specific API path format that includes /data/:

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

This /data/ segment distinguishes secret data from metadata and configuration endpoints. You’ll see this reflected in the Itential Platform configuration.

Enable kv-v2 secrets engine

$
vault secrets enable kv-v2

Configure Vault properties

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

Configuration parameters

Token-based authentication

Example configuration for token-based authentication:

1
"vaultProps": {
2
  "url": "http://localhost:8200",
3
  "authMethod": "token",
4
  "token": "/opt/vault/token.txt",
5
  "endpoint": "kv-v2/data",
6
  "readOnly": false
7
}

AppRole authentication

Example configuration for AppRole authentication:

1
"vaultProps": {
2
  "url": "http://localhost:8200",
3
  "authMethod": "approle",
4
  "role_id": "cfb83d9f-fd94-e046-71e2-dcd51147288d",
5
  "secret_id": "68df6e13-02b2-b60d-a39f-f8b879277d48",
6
  "endpoint": "kv-v2/data",
7
  "readOnly": false
8
}

File path structure

The endpoint path can be customized. Here’s an example URL structure where v1 is a hard-coded file path in Itential Platform:

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

URL components:

• http://localhost:8200 - Vault server address
• /v1 - Vault API version
• /kv-v2 - Secrets engine mount point
• /data - kv-v2 data endpoint (required for accessing secret values)

Configure readOnly property

The readOnly property in vaultProps controls how secret data is written to Vault. This property defaults to false.

When set to true:

• UI masking is disabled
• Clear text is shown
• Custom user decorations are ignored
• Itential Platform will not write data to Vault

Verify configuration

After enabling kv-v2 and configuring Vault properties:

$
sudo systemctl restart itential-platform

$
sudo journalctl -u itential-platform -f

Additional resources

• HashiCorp Vault secrets engine documentation
• kv-v2 secrets engine reference
• Secrets engine tutorial

Next steps