> This page is for Itential Platform On-Prem, version 6 (default).
> For other versions, use one of these documentation indexes:
> - 6 (default): https://docs-test.itntl.com/itential-platform/6/llms.txt
> - 2023.2: https://docs-test.itntl.com/itential-platform/2023-2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-test.itntl.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server.

# Enable the kv-v2 secrets engine

> Manage and share secrets using the Vault 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.

> **Info**
>
> 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.

> **Info**
>
> 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:

```bash
# 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:

```bash
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).

## 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:

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

> **Info**
>
> 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.

> **Info**
>
> 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:

```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
}
```

> **Info**
>
> 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.

> **Warn**
>
> 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:

```bash
sudo systemctl restart itential-platform
```

### Check the Platform logs

Check the Platform logs for Vault messages:

```bash
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](./create-secrets).

## Additional resources

* [Secrets engines](https://learn.hashicorp.com/vault/getting-started/secrets-engines) in the HashiCorp Vault documentation
* [KV secrets engine version 2](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) in the HashiCorp Vault documentation
* [Secrets engines overview](https://www.vaultproject.io/docs/secrets) in the HashiCorp Vault documentation

## What's next

#### [Create secrets](./create-secrets)

#### [Automatic encryption](/itential-platform/secrets/hashicorp/automatically-encrypt-properties)