> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Enable the kv-v2 secrets engine > Manage and share secrets using the Vault Kv-V2 secrets engine Itential supports only kv-v2. kv-v1 is not supported. 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 Kv-v2 is HashiCorp's recommended version for production use. It supersedes KV-V1, which lacks versioning and soft delete capabilities. ### How versioning works Each time you update a secret, kv-v2 creates a new version while preserving previous versions: ```bash # 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/ ``` 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 ### Enable the engine Run the following command to enable the KV secrets engine. Version 2 is recommended for Vault. ```bash vault secrets enable kv-v2 ``` ### Update properties file Navigate to `/opt/pronghorn/current` and edit the `properties.json` file with the location of the `token.txt` file. See [Configure Vault properties](#configure-vault-properties) for details. ## 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 to connect to Vault, including hostname and port | | `token` | Yes | `/file/path/token.txt` | File path to a document containing the authentication token | | `endpoint` | Yes | `secret/data` | The endpoint for the secrets engine type | | `readOnly` | Yes | `true` | Manages how secret data is written to Vault. Itential strongly recommends read-only access to vault | | `authMethod` | No | `token` | Authorization method: `token` or `approle` | | `role_id` | No | `""` | Vault RoleId for AppRole authentication | | `secret_id` | No | `""` | Vault SecretID for AppRole authentication | | `namespace` | No | `""` | The Vault Enterprise namespace to scope secret operations to. Required for multi-tenant Vault Enterprise configurations. | ### Token-based authentication Example configuration for token-based authentication: ```json "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 required by kv-v2 to access secret data. This distinguishes it from metadata or configuration endpoints. An unspecified `authMethod` defaults to token-based authentication, maintaining compatibility with previous Itential Platform configurations. ### AppRole authentication Example configuration for AppRole authentication: ```json "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 } ``` Setup of AppRole authentication and generation of `role_id` and `secret_id` must be done separately, including setting valid policies and TTL/usage limits. ### Namespace Platform 6.3.4+ If your Vault server uses [namespaces](https://developer.hashicorp.com/vault/docs/enterprise/namespaces), set `namespace` to scope all of Platform's secret operations to that namespace. This works with either `token` or `approle` authentication. ```json "vaultProps": { "url": "http://localhost:8200", "authMethod": "token", "token": "/opt/vault/token.txt", "endpoint": "kv-v2/data", "readOnly": true, "namespace": "engineering" } ``` A Platform instance connects to a single Vault namespace at a time. To use different namespaces across environments, configure each environment's Platform instance separately. Leave `namespace` unset if you're connecting to Vault's root namespace or to a Vault open source installation. You can also set this value with the `ITENTIAL_VAULT_NAMESPACE` environment variable instead of `properties.json`. ### 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 `true`. 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 If you change `readOnly` from `false` to `true` after storing passwords in Vault, all passwords will be lost and must be set manually. ## Verify configuration After enabling kv-v2 and configuring Vault properties: ### Restart Itential Platform Restart Itential Platform to apply the configuration changes. ```bash sudo systemctl restart itential-platform ``` ### Check Platform logs Review Platform logs to confirm successful Vault connection: ```bash sudo journalctl -u itential-platform -f ``` Look for messages indicating successful Vault authentication. ### Test secret storage Create a test secret in Vault and verify Platform can retrieve it. See [Create secrets](./create-secrets) for details. ## Additional resources * [HashiCorp Vault secrets engine documentation](https://learn.hashicorp.com/vault/getting-started/secrets-engines) * [kv-v2 secrets engine reference](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) * [Secrets engine tutorial](https://www.vaultproject.io/docs/secrets) ## Next steps #### [Create secrets](./create-secrets) #### [Automatic encryption](/itential-platform/secrets/hashicorp/automatically-encrypt-properties)