HashiCorp Vault integration¶
Percona Server for MongoDB is integrated with HashiCorp Vault. HashiCorp Vault supports different secrets engines. Percona Server for MongoDB only supports the HashiCorp Vault back end with KV Secrets Engine - Version 2 (API) with versioning enabled.
HashiCorp Vault Documentation: How to configure the KV Engine
HashiCorp Vault Parameters¶
|Command line||Configuration file||Type||Description|
|vaultServerName||security.vault.serverName||string||The IP address of the Vault server|
|vaultPort||security.vault.port||int||The port on the Vault server|
|vaultTokenFile||security.vault.tokenFile||string||The path to the vault token file. The token file is used by MongoDB to access HashiCorp Vault. The vault token file consists of the raw vault token and does not include any additional strings or parameters.
Example of a vault token file:
|vaultSecret||security.vault.secret||string||The path to the Vault secret. The Vault secret path format must be
Starting with version 6.0.5-4, a distinct Vault secret path for every replica set member is no longer mandatory. In earlier versions, it is recommended to use different secret paths for every database node in the entire deployment to avoid issues during the master key rotation.
|unsigned long||(Optional) The version of the Vault secret to use|
|switch||When enabled, rotates the master key and exits|
|string||The path to the TLS certificate file|
|switch||Disables secure connection to Vault using SSL/TLS client certificates|
Config file example
security: enableEncryption: true vault: serverName: 127.0.0.1 port: 8200 tokenFile: /home/user/path/token secret: secret/data/hello
During the first run of the Percona Server for MongoDB, the process generates a secure key and writes the key to the vault.
During the subsequent start, the server tries to read the master key from the vault. If the configured secret does not exist, vault responds with HTTP 404 error.
Namespaces are isolated environments in Vault that allow for separate secret key and policy management.
You can use Vault namespaces with Percona Server for MongoDB. Specify the namespace(s) for the
security.vault.secret option value as follows:
For example, the path to secret keys for namespace
test on the secrets engine
secret will be
Targeting a namespace in Vault configuration¶
You have the following options of how to target a particular namespace when configuring Vault:
- Set the VAULT_NAMESPACE environment variable so that all subsequent commands are executed against that namespace. Use the following command to set the environment variable for the namespace
$ export VAULT_NAMESPACE=test
-namespaceflag in commands
Key rotation is replacing the old master key with a new one. This process helps to comply with regulatory requirements.
To rotate the keys for a single
mongod instance, do the following:
--vaultRotateMasterKeyoption via the command line or
security.vault.rotateMasterKeyto the config file.
mongodprocess with the selected option, the process will perform the key rotation and exit.
Remove the selected option from the startup command or the config file.
Rotating the master key process also re-encrypts the keystore using the new master key. The new master key is stored in the vault. The entire dataset is not re-encrypted.
Key rotation in replica sets¶
Starting with version 6.0.5-4, you can store the master key at the same path on every replica set member in your entire deployment. Vault assigns different versions to the master keys stored at the same path. The path and the version serve as the unique identifier of a master key. The
mongod server stores that identifier and uses it to retrieve the correct master key from the Vault server during the restart.
In versions 6.0.4-3 and earlier, every
mongod node in a replica set in your entire deployment must have a distinct path to the master keys on a Vault server.
The key rotation steps are the following:
- Rotate the master key for the secondary nodes one by one.
- Step down the primary and wait for another primary to be elected.
- Rotate the master key for the previous primary node.
Get expert help¶
If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.
Created: December 7, 2022