Skip to main content
Loading

Optional security with Hashicorp Vault integration

You can configure certain sensitive Aerospike server configuration parameters to rely on your implementation of Hashicorp's Vault service.

The Hashicorp Vault configuration is optional. It is an alternative to the normal configuration.

Configuration parameters that can be secured via Vault​

The following parameters can be secured with Vault.

note

The ca-file parameter cannot be configured on the Vault service.

High-level overview to Aerospike/Vault integration​

In the Aerospike configuration file's service stanza, you define Vault-related parameters for the Aerospike node to securely connect to your Vault service, including a base URL, Transport Layer Security (TLS) certificate for authentication of the Vault server, a Vault token to authenticate the Aerospike server to the Vault service, and other settings.

For each configuration parameter you want to secure via Vault:

  • In your Vault system, you define that parameter's value as a secret. The value must be Base64-encoded.
  • In the Aerospike configuration file, for that parameter, you put the the literal vault: followed by the location of that secret in your Vault system.

At runtime, the Aerospike server constructs a URL based on the values of the Vault-related parameters in the service stanza and the configuration parameter value to retrieve the secret via Vault's REST API HTTPS GET.

Supported Vault secrets engines​

Aerospike supports the following Vault secret engines:

Preparation and prerequisites​

Have the following ready:

  • A functional Vault service. The details here assume that you have working knowledge of your Vault implementation.
  • IP addresses or domain names of Vault servers and their ports.
  • TLS certificates for authentication of the Vault server.
  • Vault token for authentication of the Aerospike server.
  • List of Aerospike parameters to secure via vault, including their desired values.
  • Vault secrets for those parameters with Base64-encoded values.

IP addresses or domain names of Vault servers​

You can have as many Vault servers as you want and each Aerospike node can operate with whichever Vault server you like. Each node of a cluster can have a unique value of the configuration parameter vault-url, which defines the IP address or domain name and port of a Vault server.

See vault-url in Required Vault parameters in service stanza.

TLS authentication of Vault server​

TLS authentication is required for the Aerospike server to identify the Vault server.

As with standard fields of TLS authentication like Subject Alternative Name (SAN), you can configure your certificates to the level of security you want, such as Aerospike cluster-wide or each individual node of a cluster.

See vault-ca in Required Vault parameters in service stanza.

Vault token to authenticate Aerospike server​

Instead of relying on TLS, the Vault server identifies the Aerospike server process by way of a Vault token in a file on the Aerospike node specified by the configuration parameter vault-token-file.

Updating the Vault token​

Starting with server 6.3, you can update the Vault token used by Aerospike during runtime.

  1. Write the new token in the Vault token file.
  2. Dynamically change the vault-token-file configuration parameter to the token file path, which can remain the same path.

Aerospike will pick up the new Vault token and use it.

See vault-token-file in Required Vault parameters in service stanza.

Vault namespace (for use with Vault Enterprise)​

As of server version 6.3, Aerospike supports Vault Enterprise, including its namespaces enterprise feature. Specify a namespace with the configuration parameter vault-namespace.

Aerospike configuration parameter names​

The names of secrets on the Vault system must be unique. If you are storing secrets for each unique node of a cluster, the name of a secret for each node must be different from the name of that secret for all the other nodes.

For clarity and ease of maintenance and administration, in your Vault system, consider a naming scheme for the Aerospike-related secret that includes the name of the configuration parameter itself. For example, for the configuration parameter encryption-key-file, store the value in a Vault secret whose name includes the string encryption-key-file.

Aerospike configuration parameter values​

Prepare the values of the Aerospike configuration parameters you want to secure with Vault. The value of a parameter is the same whether you use the normal Aerospike definition or store the value in a Vault secret, except the value in Vault must be Base64-encoded.

For example, without Vault, the parameter encryption-key-file points to a file that contains a user-supplied encryption key for enabling encryption-at-rest.

With Vault, that user-supplied encryption key is stored in Vault and identified by its secret name. The value of the encryption-key-file parameter in the Aerospike configuration file is the literal vault: followed by the name of that secret.

Base64-encoding of secret values in Vault​

The values of all secrets in Vault must be Base64-encoded. Note that embedding non-trailing whitespace in Base64-encoded secrets is not supported. For instance, the command line tool base64 from GNU Coreutils inserts line breaks every 76 characters by default, breaking the decoding. This can be addressed by adding -w 0 to its command line.

Storing Aerospike secrets in Vault​

Each Aerospike configuration parameter that is going to be secured with Vault must be stored as an individual Vault KV engine secret. The name of this secret on the Vault server must be identical to the Aerospike configuration parameter name. The secret must have a key-value pair with a key named with the literal value key. Aerospike does not support secrets with multiple key-value pairs at this point of time.

Required Vault parameters in service stanza​

The following Vault-related parameters in the service stanza are required.

The values shown here are only examples.

service {    
    ...
    vault-ca  /some/secure/path/vaultcert.pem
    vault-url https://10.0.0.99:8200
    vault-path secret/aerospike
    vault-token-file /some/path/for/auto-auth/or/orchestrator/injection
    # vault-namespace asd # (optional) the Vault Enterprise namespace to use
    ...
}
Required parameter nameDescription
vault-caPath on Aerospike node to TLS certificate for authentication with Vault server.
vault-urlProtocol, domain name or IP address, and port of Vault service.
vault-pathThe path on the Vault system to the stored secret.

Do not add the exact secret name as a suffix; this is supplied as the value of the Aerospike configuration parameter.

The version (v1 or v2) may need to be added at the beginning of the path depending on the Vault service configuration.
vault-token-filePath on Aerospike node to a file that contains a token that identifies the Aerospike server to the Vault server. This token is either from your orchestration system or a manual definition on the Vault system.

The optional vault-namespace was added in server 6.3, and supports Vault namespaces in Vault Enterprise.

Literal vault: and Aerospike configuration parameter​

For the Aerospike configuration parameter, the value must start with the literal prefix vault: and be followed by the name of the secret on the Vault service.

Example configuration parameter in configuration file​

For namespace test, the storage-engine device substanza shows that the parameter encryption-key-file points to a Vault secret.

Examples of secret name for a three-node Aerospike cluster

NodeName of secret in VaultValue of configuration parameter for each node
Node 1encryption-key-file-node1vault:encryption-key-file-node1
Node 2encryption-key-file-node2vault:encryption-key-file-node2
Node 3encryption-key-file-node2vault:encryption-key-file-node3

So the following is in the configuration file for Node 1.

namespace test {
   ...
   storage-engine device {
      device /dev/sda1
      ...
      encryption-key-file vault:encryption-key-file-node1
   }
   ...
}

Example construction of a Vault URL based on configuration parameters​

Using the example values from Required Vault parameters in service stanza and Example configuration parameter in configuration file to retrieve the encryption-key-file secret, the Aerospike Server constructs URL the following.

vault-urlvault-pathencryption-key-file = vault:encryption-key-value-node1
https://10.0.0.99:8200secret/aerospikeencryption-key-file-node1

Result:

https://10.0.0.99:8200/secret/aerospike/encryption-key-file-node1

If an Aerospike parameter can be changed dynamically with asinfo without Vault integration, it can also be changed dynamically with Vault integration.

Vault plugin​

A community support Vault plugin is available in the vault-plugin-database-aerospike git repository.

Last updated on