# HashiCorp Vault

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

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

      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:

      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:

      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.

## 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. |
| `convert-to-base64` | If `true`, Secret Agent converts secret values to base64-encoded format |  |
| `resources` | Contains the mount point, secret name, and version of the secret | Required. |
| `mount` | Mount point (path) of the secret engine |  |
| `secret` | Name of the secret |  |
| `version` | Version of the secret. Default `0` fetches the latest version. |  |