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 only.

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

1. Token auth method
2. Username and password auth method
3. TLS certificates auth method
4. AppRole auth method

Resource entries

Under resources, each key is an alias that Aerospike Database references in secrets:resource:key paths. Each alias maps to a KV mount, secret path, and optional version:

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:

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:

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:

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.

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:

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 and a 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:

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

Example: HTTP proxy with AppRole

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)

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