Manage Customer Keys with Google Cloud KMS
On this page
This feature is not available for M0 free clusters, M2, and
M5 clusters. To learn more about which features are unavailable,
see Atlas M0 (Free Cluster), M2, and M5 Limitations.
Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.
Atlas uses your Google Cloud Service Account Key to encrypt and decrypt your MongoDB master keys. These MongoDB master keys are used to encrypt cluster database files and cloud providers snapshots.
When you use your own cloud provider KMS, Atlas automatically rotates the MongoDB master keys every 90 days. These keys are rotated on a rolling basis and the process does not require the data to be rewritten.
Atlas encrypts your data at rest using encrypted storage media. Using keys you manage with Google Cloud KMS, Atlas encrypts your data a second time when it writes it to the MongoDB encrypted storage engine. You use your Google Cloud SAK to encrypt the MongoDB master encryption keys.
This page covers configuring customer key management using Google Cloud on your Atlas project.
You must configure customer key management for the Atlas project before enabling it on clusters in that project.
Enable Customer-Managed Keys with Google Cloud KMS
Prerequisites
To enable customer-managed keys with Google Cloud KMS for a MongoDB project, you must have:
- Use an M10 or larger cluster.
- Use Cloud Backups to encrypt your backup snapshots. Legacy Backups are not supported.
- Your symmetric Google Cloud Service Account Key.
- The Key Version Resource ID associated with your Service Account Key.
A Google Cloud service account with credentials specified in your Service Account Key with sufficient permissions to:
- Get the Service Account Key version
- Encrypt data with the Service Account Key version
- Decrypt data with the Service Account Key
NoteThe key, not the key version, handles decryption.
- If your Google Cloud KMS configuration requires it, allow access from Atlas IP addresses and the public IP addresses or DNS hostnames of your cluster nodes so that Atlas can communicate with your KMS. If the node IP addresses change, you must update your configuration to avoid connectivity interruptions.
See the Google Cloud documentation to learn how to:
Enable Customer-Managed Keys for a Project
You must enable customer key management for a project before you can enable it on a cluster in that project.
Navigate to the Advanced page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- Click Advanced in the sidebar.
Toggle the button next to Encryption at Rest using your Key Management to On.
Select Google Cloud KMS.
Enter your Service Account Key.
Your Service Account Key should be formatted as a JSON object. It contains the encryption credentials for your GCP service account.
Enter the Key Version Resource ID.
Your key version resource ID is the fully-qualified resource name for a CryptoKeyVersion.
Click Save.
Enable Customer Key Management for an Atlas Cluster
After you Enable Customer-Managed Keys for a Project, you must enable customer key management for each Atlas cluster that contains data that you want to encrypt.
You must have the Project Owner role to
enable customer key management for clusters in that project.
For new clusters, toggle the Manage your own encryption keys setting to Yes when you create the cluster.
For existing clusters:
Navigate to the Database Deployments page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- If the Database Deployments page is not already displayed, click Databases in the sidebar.
Modify the cluster's configuration.
For the cluster that contains data that you want to encrypt, click the ellipses ..., then select Edit Configuration.
Enable cluster encryption.
- Expand the Additional Settings panel.
- Toggle the Manage your own encryption keys setting to Yes.
Review and apply your changes.
- Click Review Changes.
- Review your changes, then click Apply Changes to update your cluster.
Alerts
Atlas automatically creates an encryption key rotation alert
once you configure customer key management for a project. You can reset this alert at any time by
rotating your GCP Key Version Resource ID.
Rotate your GCP Key Version Resource ID
This feature is not available for M0 free clusters, M2, and
M5 clusters. To learn more about which features are unavailable,
see Atlas M0 (Free Cluster), M2, and M5 Limitations.
Serverless instances are in preview and do not support this feature at this time. To learn more, see Serverless Instance Limitations.
When you use your own cloud provider KMS, Atlas automatically rotates the MongoDB master keys every 90 days. These keys are rotated on a rolling basis and the process does not require the data to be rewritten.
Atlas does not automatically rotate the Key Version Resource ID used for Google Cloud key management.
Atlas automatically creates an
encryption key rotation alert
to remind you to rotate your GCP Key Version Resource ID every 90 days
by default when you enable Encryption at Rest
for an Atlas project.
Prerequisites
You must create a new Service Account Key in the Google Cloud account associated with your Atlas project.
Procedure
The following procedure documents how to rotate your Atlas project Key Identifier by specifying a new Key Version Resource ID in Atlas.
Navigate to the Advanced page for your project.
- If it is not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
- If it is not already displayed, select your desired project from the Projects menu in the navigation bar.
- Click Advanced in the sidebar.
Click Rotate Keys .
Update the GCP Key details.
- Click Google Cloud KMS if the Google Cloud KMS tab is not already active.
- Expand Encryption Key Credentials if the Encryption Key Credentials dialog is not already displayed.
Enter the GCP Key Version Resource ID in the Key Identifier entry.
Include the fully-qualified resource name for a CryptoKeyVersion.
Exampleprojects/my-project-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1 The encryption key must belong to the Google Cloud Service Account Key configured for your Atlas project. Click the Service Account Key section to view the currently configured Service Account Key for the project.
- Click Update Credentials.
Atlas displays a banner in the Atlas console during the Key Identifier rotation process.
Do not delete or disable the original Key Version Resource ID until your changes have deployed.
If the cluster uses Back Up Your Database Deployment, do not delete or disable the original Key Version Resource ID until you ensure that no snapshots used that key for encryption.
Alerts
Atlas resets the
encryption key rotation alert
timer at the completion of this procedure.
Related Topics
- To enable Encryption at Rest using your Key Management when deploying an Atlas cluster, see Manage Your Own Encryption Keys.
- To enable Encryption at Rest using your Key Management for an existing Atlas cluster, see Enable Encryption at Rest.
- To learn more about Encryption at Rest using your Key Management in Atlas, see Encryption at Rest using Customer Key Management.
- To learn more about MongoDB Encryption at Rest, see Encryption at Rest in the MongoDB server documentation.
- To learn more about Encryption at Rest with Cloud Backups, see Storage Engine and Cloud Backup Encryption.