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.
auth-password-file
cert-file
encryption-key-file
encryption-old-key-file
feature-key-file
key-file
key-file-password
query-user-password-file
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.
- Write the new token in the Vault token file.
- 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 name | Description |
---|---|
vault-ca | Path on Aerospike node to TLS certificate for authentication with Vault server. |
vault-url | Protocol, domain name or IP address, and port of Vault service. |
vault-path | The 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-file | Path 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
Node | Name of secret in Vault | Value of configuration parameter for each node |
---|---|---|
Node 1 | encryption-key-file-node1 | vault:encryption-key-file-node1 |
Node 2 | encryption-key-file-node2 | vault:encryption-key-file-node2 |
Node 3 | encryption-key-file-node2 | vault: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-url | vault-path | encryption-key-file = vault:encryption-key-value-node1 |
---|---|---|
https://10.0.0.99:8200 | secret/aerospike | encryption-key-file-node1 |
Result:
https://10.0.0.99:8200/secret/aerospike/encryption-key-file-node1
Dynamically changing Vault-related parameters
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.