---
title: "HashiCorp Vault"
description: "Configure Aerospike Secret Agent to fetch secrets from HashiCorp Vault KV (V2) Secrets Engine."
---

# HashiCorp Vault

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

::: caution
Configuring Vault directly in the Aerospike Database configuration is deprecated in Database 7.0.0. Use Secret Agent to fetch secrets from Vault.
:::

HashiCorp Vault supports multiple secret engines. Secret Agent supports fetching secrets from the [KV (V2) Secrets Engine](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2) only.

Secret Agent can authenticate with the HashiCorp Vault server using one of the following methods:

1.  [Token auth method](https://developer.hashicorp.com/vault/docs/auth/token)
2.  [Username and password auth method](https://developer.hashicorp.com/vault/docs/auth/userpass)
3.  [TLS certificates auth method](https://developer.hashicorp.com/vault/docs/auth/cert)
4.  [AppRole auth method](https://developer.hashicorp.com/vault/docs/auth/approle)

## Resource entries

Under `resources`, each key is an alias that Aerospike Database references in [`secrets:resource:key`](https://aerospike.com/docs/database/manage/security/secrets) paths. Each alias maps to a KV mount, secret path, and optional version:

```yaml
resources:

  TestingSecret:

    mount: mysecrets

    secret: TestingSecret

    version: 0 # 0 means latest version
```

When only one resource alias is configured, the `Resource` field in Secret Agent protocol requests is optional.

## Token auth method

This method authenticates with a Vault token. You must generate a Vault token and store it in a file. Secret Agent reads the token from the file for every fetch request, so if you update the token in the file, Secret Agent uses the new token for the next request. The file must have permissions that restrict read access to the Secret Agent process.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  vault:

    endpoint: http://127.0.0.1:8200

    token-file: /path/to/token/file

    namespace: asd # (optional) Vault Enterprise namespace

    convert-to-base64: false

    resources:

      TestingSecret:

        mount: mysecrets

        secret: TestingSecret

        version: 0 # 0 means latest version

log:

  level: info
```

To configure Secret Agent with the token auth method:

1.  Enable KV (V2) Secrets Engine in Vault with mount (path) `mysecrets`.
2.  Create a secret under the `mysecrets` mount. In this example, the secret is named `TestingSecret`.
3.  Add one or more key-value pairs to `TestingSecret`.
4.  Generate a Vault token and store it in a file. In this example, the file is `/path/to/token/file`.
5.  Install Secret Agent on the machine.
6.  Configure Secret Agent to fetch secrets from Vault.
7.  Start Secret Agent.

## Username and password auth method

To authenticate with Vault using a username and password, create a user in Vault and store the password in a file. Secret Agent reads the password from the file and uses it to authenticate. Specify the username in the Secret Agent configuration file.

When Secret Agent authenticates with this method, it creates a Vault token to fetch secrets. If the token is renewable, Secret Agent automatically renews it before it expires. If the token is not renewable, Secret Agent creates a new token when the existing one expires, using the same username and password.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  vault:

    endpoint: http://127.0.0.1:8200

    username: testuser

    password-file: /path/to/password/file

    namespace: asd # (optional) Vault Enterprise namespace

    convert-to-base64: false

    resources:

      TestingSecret:

        mount: mysecrets

        secret: TestingSecret

        version: 0 # 0 means latest version

log:

  level: info
```

To configure Secret Agent with the username and password auth method:

1.  Enable KV (V2) Secrets Engine in Vault with mount (path) `mysecrets`.
2.  Create a secret under the `mysecrets` mount. In this example, the secret is named `TestingSecret`.
3.  Add one or more key-value pairs to `TestingSecret`.
4.  Create a username and password in Vault. In this example, the username is `testuser` and the password is stored in `/path/to/password/file`.
5.  Verify that `testuser` has policies attached that allow reading `TestingSecret`.
6.  Install Secret Agent on the machine.
7.  Configure Secret Agent to fetch secrets from Vault.
8.  Start Secret Agent.

Sample Vault policy to read secrets under the `mysecrets` mount:

```hcl
path "mysecrets/*" {

  capabilities = ["read", "list"]

}
```

## TLS certificates auth method

With this method, no tokens or passwords are stored on the machine. The TLS certificates auth method authenticates using SSL/TLS client certificates that are either signed by a CA or self-signed. The Vault server determines whether a matching certificate exists to authenticate Secret Agent. On success, the auth method returns a token. Token renewal works the same way as the [username and password auth method](#username-and-password-auth-method).

::: note
The Vault server must be configured with TLS enabled. Both `tls_disable` and `tls_disable_client_certs` must be `false` in the Vault configuration, because certificates are sent through the TLS connection.
:::

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  vault:

    endpoint: https://127.0.0.1:8200

    tls-auth-mount: authcerts

    client-cert-file: /path/to/client/cert/file

    client-key-file: /path/to/client/key/file

    ca-file: /path/to/ca/file

    namespace: asd # (optional) Vault Enterprise namespace

    convert-to-base64: false

    resources:

      TestingSecret:

        mount: mysecrets

        secret: TestingSecret

        version: 0 # 0 means latest version

log:

  level: info
```

To configure Secret Agent with the TLS certificates auth method:

1.  Create a TLS auth method in Vault. In this example, the mount (path) is `authcerts`.
2.  Enable KV (V2) Secrets Engine in Vault with mount (path) `mysecrets`.
3.  Create a secret under the `mysecrets` mount. In this example, the secret is named `TestingSecret`.
4.  Add one or more key-value pairs to `TestingSecret`.
5.  Verify that the TLS auth method has policies attached that allow reading `TestingSecret`.
6.  Install Secret Agent on the machine.
7.  Configure Secret Agent to fetch secrets from Vault.
8.  Start Secret Agent.

## AppRole authentication

With this method, Secret Agent authenticates to HashiCorp Vault using a [role ID](https://developer.hashicorp.com/vault/docs/auth/approle#role-id) and a [secret ID](https://developer.hashicorp.com/vault/docs/auth/approle#secret-id). This feature is available in Secret Agent 1.4.0 and later.

### Security requirements

Store the secret ID in a file on the host. Restrict read access to this file to the Secret Agent process.

### Token lifecycle

At startup, Secret Agent validates that `secret-id-file` is readable.

On the first secret request, Secret Agent reads the secret ID from the file and logs in to Vault.

-   If the returned token is renewable, Secret Agent automatically renews it before it expires.
-   If the token is not renewable, Secret Agent re-authenticates using the same `secret-id-file` before the token expires.

The AppRole auth mount defaults to `approle`. If your Vault deployment uses a different mount path, set `approle-mount` in the Secret Agent configuration file.

Sample configuration file:

```yaml
service:

  tcp:

    endpoint: 0.0.0.0:3005

secret-manager:

  vault:

    endpoint: https://127.0.0.1:8200

    ca-file: /path/to/ca/file

    role-id: c49b442f-bf4b-0c82-a776-42699f521ccf

    secret-id-file: /path/to/secret-id/file

    approle-mount: approle # optional; default is approle

    namespace: asd # (optional) Vault Enterprise namespace

    convert-to-base64: false

    resources:

      TestingSecret:

        mount: mysecrets

        secret: TestingSecret

        version: 0 # 0 means latest version

log:

  level: info
```

To configure Secret Agent with the AppRole auth method:

1.  Enable the [AppRole auth method](https://developer.hashicorp.com/vault/docs/auth/approle) in Vault and create a role with policies that allow reading your KV secrets.
2.  Obtain the role ID and generate a secret ID for that role.
3.  Store the secret ID in a file readable by Secret Agent. In this example, the file is `/path/to/secret-id/file`.
4.  Enable KV (V2) Secrets Engine in Vault with mount (path) `mysecrets`.
5.  Create a secret under the `mysecrets` mount. In this example, the secret is named `TestingSecret`.
6.  Add one or more key-value pairs to `TestingSecret`.
7.  Install Secret Agent on the machine.
8.  Configure Secret Agent with `role-id` and `secret-id-file`.
9.  Start Secret Agent.

::: note
Configure exactly one Vault authentication method. Secret Agent rejects configurations that combine AppRole with `token-file`, username and password, or TLS certificate authentication.
:::

## Configuration parameters

| Parameter | Description | Notes |
| --- | --- | --- |
| `endpoint` | Vault server endpoint | Required. Can be `http` or `https`. |
| `ca-file`/`ca-path` | File or path to the CA certificate | Required if the Vault server uses `https`. |
| `namespace` | Namespace for authentication | Required when using Vault Enterprise or HashiCorp Cloud Platform (HCP) Vault. |
| `token-file` | Path to the file containing the Vault token | Required when using the token auth method. |
| `username` | Username for authentication | Required when using the username and password method. |
| `password-file` | Path to the file containing the password | Required when using the username and password method. |
| `tls-auth-mount` | Mount point of the TLS certificates auth method | Required when using the TLS certificates method. |
| `client-cert-file` | Path to the client certificate file | Required when using the TLS certificates method. |
| `client-key-file` | Path to the client key file | Required when using the TLS certificates method. |
| `role-id` | Vault AppRole role ID | Required when using the AppRole auth method. |
| `secret-id-file` | Path to the file containing the AppRole secret ID | Required when using the AppRole auth method. |
| `approle-mount` | Mount point of the AppRole auth method | Optional. Default is `approle`. |
| `convert-to-base64` | If `true`, Secret Agent converts secret values to base64-encoded format |  |
| `resources` | Map of resource aliases to Vault KV paths | Required. |
| `resources.<alias>.mount` | KV secrets engine mount point | Required for each resource entry. |
| `resources.<alias>.secret` | Secret path under the mount | Required for each resource entry. |
| `resources.<alias>.version` | Secret version; `0` fetches the latest version | Optional. Default `0`. |

## Proxy

When Secret Agent must reach Vault over a corporate proxy, set `HTTP_PROXY` or `HTTPS_PROXY` depending on whether `endpoint` uses `http://` or `https://`.

You can also set `proxy.url` under the `vault` section to override environment variables for Vault traffic only.

Local Vault (`http://127.0.0.1:8200`) is automatically excluded from the proxy together with other localhost and metadata hosts.

Proxy TLS options under `proxy.tls` apply only to TLS to the proxy and are independent of Vault server TLS (`ca-file`, `client-cert-file`, and related options).

To understand proxy architecture, configure environment variables (including `NO_PROXY`), set up TLS, and validate your startup configuration, see [Configure a proxy](https://aerospike.com/docs/database/tools/secret-agent/proxy).

### Example: HTTP proxy with AppRole

```yaml
secret-manager:

  vault:

    endpoint: https://vault.corp.example.com:8200

    ca-file: /etc/aerospike-secret-agent/vault-ca.pem

    role-id: c49b442f-bf4b-0c82-a776-42699f521ccf

    secret-id-file: /etc/aerospike-secret-agent/secret-id

    proxy:

      url: http://proxy.corp.example.com:3128

    resources:

      appConfig:

        mount: secret

        secret: my-app/config
```

### Example: HTTPS proxy with private CA and mutual TLS (mTLS)

```yaml
secret-manager:

  vault:

    endpoint: https://vault.corp.example.com:8200

    ca-file: /etc/aerospike-secret-agent/vault-ca.pem

    role-id: c49b442f-bf4b-0c82-a776-42699f521ccf

    secret-id-file: /etc/aerospike-secret-agent/secret-id

    proxy:

      url: https://proxy.corp.example.com:3128

      tls:

        ca-file: /etc/aerospike-secret-agent/proxy-ca.crt

        cert-file: /etc/aerospike-secret-agent/proxy-client.crt

        key-file: /etc/aerospike-secret-agent/proxy-client.key

        tls-name: proxy.corp.example.com

    resources:

      appConfig:

        mount: secret

        secret: my-app/config
```