Customer Key Management with AWS KMS¶
This feature is not available for M0
(Free Tier), M2
, and
M5
clusters. To learn more about which features are unavailable,
see Atlas M0 (Free Tier), M2, and M5 Limitations.
Atlas uses your AWS customer master key (CMK) in the AWS Key Management Service (KMS) 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 AWS KMS , Atlas encrypts your data a second time when it writes it to the MongoDB encrypted storage engine. You use your AWS CMK to encrypt the MongoDB master encryption keys. Oplog data is also encrypted with your CMK .
This page covers configuring customer key management using AWS KMS on your Atlas project.
You must configure customer key management for the Atlas project before enabling it on clusters in that project.
Prerequisites¶
To enable customer-managed keys with AWS KMS for a MongoDB project, you must:
- Use an M10 or larger cluster.
- Use Cloud Backups to encrypt your backup snapshots. Legacy Backups are not supported.
- Have an AWS customer master key (CMK ). To learn how to create a key, see Creating Keys in the AWS documentation.
Have an AWS IAM user with sufficient privileges. Atlas must have permission to perform the following actions with your key:
NoteIf you wish to use the AWS CMK with an AWS IAM user from a different AWS account instead of the IAM user who created the AWS CMK, ensure you have sufficient privileges:
- Add a key policy statement under the AWS CMK to include the external AWS account.
- Add an IAM inline policy for the IAM user in the external AWS account.
For a comprehensive discussion of IAM roles and customer master keys, see the AWS documentation.
After confirming the above privileges, you can follow the usual steps to configure the KMS settings in Atlas, with the following exception:
- You must provide the full ARN for
the CMK (e.g.
arn:aws:kms:eu-west-2:111122223333:key/12345678-1234-1234-1234-12345678
) instead of the master key ID (e.g.12345678-1234-1234-1234-12345678
) in the CMK ID field.
To learn how to create an IAM user, see IAM Users in the AWS documentation.
Atlas uses the same IAM user credentials and CMK settings for all clusters in a project for which Encryption at Rest is enabled.
- If your AWS 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.
Procedures¶
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.¶
Configure the KMS settings.¶
Enter the following information:
Field Action Customer Master Key ID Enter your AWS customer master key ID. Customer Master Key Region Select the AWS region in which you created your AWS CMK .
NoteAtlas only lists AWS regions that support AWS KMS .
Access Key ID Enter your IAM user's access key ID. Secret Access Key Enter your IAM user's secret access key. - 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 Clusters 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 Clusters page is not already displayed, click Clusters 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.
Disable Customer-Managed Keys for a Project¶
You must disable customer key management on each cluster in a project before you can disable the feature for the project.
Alerts¶
Atlas automatically creates an
customer master key rotation alert
once you configure Encryption at Rest for a project.
To reset this alert, Rotate your AWS Customer Master Key.
Related Topics¶
- To enable Encryption at Rest when deploying an Atlas cluster, see Manage Your Own Encryption Keys.
- To enable Encryption at Rest for an existing Atlas cluster, see Enable Encryption at Rest.
- To rotate the currently configured CMK or changing the IAM user credentials for a Atlas project, see Rotate your AWS Customer Master Key.