Skip to content
logo
Percona Server for MongoDB 4.2
HashiCorp Vault integration
Initializing search
    percona/psmdb-docs
    percona/psmdb-docs
    • Home
    • Percona Server for MongoDB feature comparison
      • Overview
      • Install Percona Server for MongoDB on Debian and Ubuntu
      • Install Percona Server for MongoDB on Red Hat Enterprise Linux and derivatives
      • Install Percona Server for MongoDB from binary tarball
      • Run Percona Server for MongoDB in a Docker container
        • Percona Memory Engine
        • Hot Backup
        • $backupCursor and $backupCursorExtend aggregation stages
        • Authentication
        • Enable authentication
        • Set up LDAP authentication with SASL
        • Set up x.509 authentication and LDAP authorization
        • Setting up Kerberos authentication
        • LDAP authorization
        • Set up LDAP authentication and authorization using NativeLDAP
        • Data at rest encryption
        • HashiCorp Vault integration
          • HashiCorp Vault Parameters
          • Namespaces
            • Targeting a namespace in Vault configuration
          • Key Rotation
            • Key rotation in replica sets
        • Using the Key Management Interoperability Protocol (KMIP)
        • Local key management using a keyfile
        • Migrate from key file encryption to HashiCorp Vault encryption
      • Auditing
      • Profiling rate limit
      • Log redaction
      • Additional text search algorithm - ngram
      • Tune parameters
        • Upgrade from 4.0 to 4.2
        • Upgrade Percona Server for MongoDB
      • Uninstall Percona Server for MongoDB
      • Release notes index
      • Percona Server for MongoDB 4.2.24-24 (2023-03-09)
      • Percona Server for MongoDB 4.2.23-23 (2022-11-08)
      • Percona Server for MongoDB 4.2.22-22 (2022-09-06)
      • Percona Server for MongoDB 4.2.21-21 (2022-06-29)
      • Percona Server for MongoDB 4.2.20-20 (2022-05-23)
      • Percona Server for MongoDB 4.2.19-19 (2022-03-29)
      • Percona Server for MongoDB 4.2.18-18 (2022-01-19)
      • Percona Server for MongoDB 4.2.17-17 (2021-10-11)
      • Percona Server for MongoDB 4.2.15-16 (2021-07-26)
      • Percona Server for MongoDB 4.2.14-15 (2021-05-13)
      • Percona Server for MongoDB 4.2.13-14 (2021-04-01)
      • Percona Server for MongoDB 4.2.12-13 (2021-02-03)
      • Percona Server for MongoDB 4.2.11-12 (2020-12-07)
      • Percona Server for MongoDB 4.2.10-11 (2020-11-02)
      • Percona Server for MongoDB 4.2.9-10 (2020-10-09)
      • Percona Server for MongoDB 4.2.9-9 (2020-09-03)
      • Percona Server for MongoDB 4.2.8-8 (2020-07-07)
      • Percona Server for MongoDB 4.2.7-7 (2020-06-04)
      • Percona Server for MongoDB 4.2.6-6 (2020-05-07)
      • Percona Server for MongoDB 4.2.5-5 (2020-04-02)
      • Percona Server for MongoDB 4.2.3-4 (2020-02-20)
      • Percona Server for MongoDB 4.2.2-3 (2019-12-24)
      • Percona Server for MongoDB 4.2.1-1 (2019-11-13)
      • Percona Server for MongoDB 4.2.0-1 (2019-09-09)
    • Glossary
      • Copyright and Licensing Information
      • Trademark Policy

    • HashiCorp Vault Parameters
    • Namespaces
      • Targeting a namespace in Vault configuration
    • Key Rotation
      • Key rotation in replica sets

    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.

    See also

    Percona Blog: Using Vault to Store the Master Key for Data at Rest Encryption on Percona Server for MongoDB

    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:

    s.uTrHtzsZnEE7KyHeA797CkWA
    vaultSecret security.vault.secret string The path to the vault secret. Every replica set member must have its own distinct vault secret. It is recommended to use different secret paths for every database node.

    Note that vault secrets path format must be <vault_secret_mount>/data/<custom_path>

    where:
    * <vault_secret_mount> is your Vault KV Secrets Engine;
    * data is the mandatory path prefix required by Version 2 API;
    * <custom_path> is your secrets path.

    Example: secret_v2/data/psmdb-test/rs1-27017
    vaultRotateMasterKey security.vault.rotateMasterKey switch Enables master key rotation
    vaultServerCAFile security.vault.serverCAFile string The path to the TLS certificate file
    vaultDisableTLSForTesting security.vault.disableTLSForTesting switch Disables secure connection to

    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¶

    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:

    <namespace>/secret/data/<secret_path>
    

    For example, the path to secret keys for namespace test on the secrets engine secret will be test/secret/<my_secret_path>.

    Targeting a namespace in Vault configuration¶

    You have the following options of how to target a particular namespace when configuring Vault:

    1. 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 test:

    $ export VAULT_NAMESPACE=test
    
    2. Provide the namespace with the -namespace flag in commands

    See also

    HashiCorp Vault Documentation:

    • Namespaces

    • Secure Multi-Tenancy with Namespaces

    Key Rotation¶

    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:

    1. Stop the mongod process

    2. Add --vaultRotateMasterKey option via the command line or security.vault.rotateMasterKey to the config file.

    3. Run the mongod process with the selected option, the process will perform the key rotation and exit.

    4. Remove the selected option from the startup command or the config file.

    5. Start mongod again.

    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¶

    Every mongod node in a replica set must have its own master key. The key rotation steps are the following:

    1. Rotate the master key for the secondary nodes one by one.
    2. Step down the primary and wait for another primary to be elected.
    3. Rotate the master key for the previous primary node.

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: March 21, 2023
    Created: December 8, 2022
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.