Encrypt Data Using a Key Management Service

On this page

Prerequisites

Procedure

Important

Feature unavailable in Serverless Instances

Serverless instances don't support this feature at this time. To learn more, see Serverless Instance Limitations.

Atlas encrypts all cluster storage and snapshot volumes at rest by default. You can add another layer of security by using your cloud provider's KMS together with the MongoDB encrypted storage engine.

You can use one or more of the following customer KMS providers for encryption at rest in Atlas:

Note

The key management provider doesn't need to match the cluster cloud service provider.

To learn more about using your KMS with Atlas, see:

To manage your KMS encryption with Atlas Kubernetes Operator, you can specify and update the spec.encryptionAtRest parameter for the AtlasProject Custom Resource. Each time you change the spec field in any of the supported custom resources, Atlas Kubernetes Operator creates or updates the corresponding Atlas configuration.

Prerequisites

To configure encryption at rest using AWS KMS in Atlas Kubernetes Operator, you require:

A running Kubernetes cluster with Atlas Kubernetes Operator deployed.
The Project Owner or Organization Owner role in Atlas.
Valid key management credentials and an encryption key for AWS KMS. To learn more, see Prerequisites to Enable Customer-Managed Keys with AWS.
An assumed IAM role for your Atlas account. To set up an assumed IAM role with the Atlas Kubernetes Operator, see Set Up Unified Cloud Provider Integrations. To learn more about role-based access for an AWS encryption key, see Manage Customer Keys with AWS KMS.

Important

If you switch your encryption keys to role-based access, you can't undo the role-based access configuration and revert to credentials-based access for encryption keys on that project.

To configure encryption at rest using Azure Key Vault in Atlas Kubernetes Operator, you require:

A running Kubernetes cluster with Atlas Kubernetes Operator deployed.
The Project Owner or Organization Owner role in Atlas.
Valid key management credentials and an encryption key for Azure Key Vault. To learn more, see Prerequisites to Enable Customer-Managed Keys with Azure.

To configure encryption at rest using a Google Cloud KMS in Atlas Kubernetes Operator, you require:

A running Kubernetes cluster with Atlas Kubernetes Operator deployed.
The Project Owner or Organization Owner role in Atlas.
Valid key management credentials and an encryption key for Google Cloud KMS. To learn more, see Prerequisites to Enable Customer-Managed Keys with Google Cloud.

Procedure

Encypt your Atlas data using a customer-managed key with the following procedure:

Create a secret with your AWS credentials.

Create a secret with the values for the following parameters:

Parameter	Description
`CustomerMasterKeyID`	Unique alphanumeric string that identifies the AWS customer master key that you use to encrypt and decrypt the MongoDB master keys.
`RoleId`	Unique AWS ARN that identifies the AWS IAM role with permission to manage your AWS customer master key. To find this value: Go to the Roles section of the AWS Management Console. Click the IAM role that you edited or created for Atlas access. AWS displays the ARN in the Summary section.

To create and label a secret, run the following commands with your AWS credentials:

kubectl create secret generic aws-ear-creds \
  --from-literal="CustomerMasterKeyID=<customer-master-key>" \
  --from-literal="RoleId=<aws-arn>" \
  -n mongodb-atlas-system

kubectl label secret aws-ear-creds atlas.mongodb.com/type=credentials -n mongodb-atlas-system

Specify the `spec.encryptionAtRest.awsKms` parameter.

Add the spec.encryptionAtRest.awsKms object to the spec.encryptionAtRest array in the AtlasProject Custom Resource, including the following parameters:

Parameter	Description
`spec.encryptionAtRest.awsKms.enabled`	Flag that indicates whether this project uses AWS KMS to encrypt data at rest. To enable encryption at rest using AWS KMS, set this parameter to `true`. To disable encryption at rest using AWS KMS, set this parameter to `false`. If you disable encryption at rest using AWS KMS, Atlas Kubernetes Operator removes the configuration details.
`spec.encryptionAtRest.awsKms.region`	Label that indicates the AWS region where the customer master key exists.
`spec.encryptionAtRest.awsKms.secretRef.name`	Name of the secret that contains your AWS credentials.
`spec.encryptionAtRest.awsKms.secretRef.namespace`	Namespace that contains your AWS credentials. If unspecified, this parameter defaults to the namespace of the `AtlasProject` custom resource.

You must use a secret that contains the values for AccessKeyID, SecretAccessKey, CustomerMasterKeyID, and RoleId.

Run the following command:

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasProject
metadata:
  name: my-project
spec:
  name: Test Atlas Operator Project
  encryptionAtRest:
    awsKms:
      enabled: true
      region: us-east-1
      secretRef:
        name: aws-ear-creds
        namespace: mongodb-atlas-system
EOF

Check for successful enablement of encryption at rest on your project.

Run the following command to check whether Atlas Kubernetes Operator detects the AWS KMS configuration for your project.

kubectl get atlasprojects my-project -o=jsonpath='{.status.conditions[?(@.type=="EncryptionAtRestReadyType")].status}

true

Enable encryption at rest using customer-managed keys for your cluster.

After you enable encryption at rest using customer-managed keys for your project, you must enable it at the cluster level to encrypt data.

Run the following command to add the spec.deploymentSpec.encryptionAtRestProvider to your AtlasDeployment Custom Resource, which enables encryption at rest using your AWS key for this cluster:

cat <<EOF | kubectl apply -f -
      apiVersion: atlas.mongodb.com/v1
      kind: AtlasDeployment
      metadata:
        name: my-cluster
      spec:
        name: Test Atlas Operator Cluster
        DeploymentSpec:
          encryptionAtRestProvider: "AWS"
      EOF

Create a secret with your Azure credentials.

Create a secret with the values for the following parameters:

Parameter	Description
`KeyIdentifier`	Web address with a unique key that identifies your Azure Key Vault.
`KeyVaultName`	Unique string that identifies the Azure Key Vault that contains your key.
`Secret`	Private data associated with the Azure Key Vault tenant you specify in `spec.encryptionAtRest.azureKeyVault.tenantID`.
`SubscriptionID`	Unique 36-hexadecimal character string that identifies your Azure subscription. Azure displays the subscription ID on the subscription's details page.

To create and label a secret, run the following commands with your Azure credentials:

kubectl create secret generic azure-ear-creds \
  --from-literal="KeyIdentifier=<web-address>" \
  --from-literal="KeyVaultName=<key-vault>" \
  --from-literal="Secret=<secret>" \
  --from-literal="SubscriptionID=<subscription>" \
  -n mongodb-atlas-system

kubectl label secret azure-ear-creds atlas.mongodb.com/type=credentials -n mongodb-atlas-system

Specify the `spec.encryptionAtRest.azureKeyVault` parameter.

Add the spec.encryptionAtRest.azureKeyVault object to the spec.encryptionAtRest array in the AtlasProject Custom Resource, including the following parameters:

Parameter	Description
`spec.encryptionAtRest.azureKeyVault.azureEnvironment`	Azure deployment location where the Azure account credentials reside. Valid values include `AZURE`, `AZURE_CHINA`, and `AZURE_GERMANY`.
`spec.encryptionAtRest.azureKeyVault.clientID`	Unique 36-hexadecimal character string that identifies your Azure application.
`spec.encryptionAtRest.azureKeyVault.` `enabled`	Flag that indicates whether this project uses Azure Key Vault to encrypt data at rest. To enable encryption at rest using Azure Key Vault, set this parameter to `true`. To disable encryption at rest using Azure Key Vault, set this parameter to `false`. If you disable encryption at rest using Azure key vault, Atlas Kubernetes Operator removes the configuration details.
`spec.encryptionAtRest.azureKeyVault.resourceGroupName`	Label that identifies the Azure resource group that contains your Azure Key Vault. Azure displays the resource group name on the resource group's details page.
`spec.encryptionAtRest.azureKeyVault.secretRef.name`	Name of the secret that contains your Azure credentials.
`spec.encryptionAtRest.azureKeyVault.secretRef.namespace`	Namespace that contains your Azure credentials. If unspecified, this parameter defaults to the namespace of the `AtlasProject` custom resource.
`spec.encryptionAtRest.azureKeyVault.` `tenantID`	Unique 36-hexadecimal character string that identifies the Azure Active Directory tenant within your Azure subscription. Azure displays the tenant ID on the tenant properties page.

You must use a secret that contains the values for KeyVaultName, KeyIdentifier, Secret, and SubscriptionID.

Run the following command:

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasProject
metadata:
  name: my-project
spec:
  name: Test Atlas Operator Project
  encryptionAtRest:
    azureKeyVault:
      azureEnvironment: AZURE
      clientID: "12345678-90ab-cdef-1234-567890abcdef"
      enabled: true
      resourceGroupName: "myResourceGroup"
      tenantID: "e8e4b6ba-ff32-4c88-a9af-EXAMPLEID"
      secretRef:
        name: azure-ear-creds
        namespace: mongodb-atlas-system
EOF

Check for successful enablement of encryption at rest on your project.

Run the following command to check whether Atlas Kubernetes Operator detects the Azure Key Vault configuration for your project.

kubectl get atlasprojects my-project -o=jsonpath='{.status.conditions[?(@.type=="EncryptionAtRestReadyType")].status}

true

Enable encryption at rest using customer-managed keys for your cluster.

After you enable encryption at rest using customer-managed keys for your project, you must enable it at the cluster level to encrypt data.

Run the following command to add the spec.deploymentSpec.encryptionAtRestProvider to your AtlasDeployment Custom Resource, which enables encryption at rest using your Azure key for this cluster:

cat <<EOF | kubectl apply -f -
      apiVersion: atlas.mongodb.com/v1
      kind: AtlasDeployment
      metadata:
        name: my-cluster
      spec:
        name: Test Atlas Operator Cluster
        DeploymentSpec:
          encryptionAtRestProvider: "AZURE"
      EOF

Create a secret with your Google Cloud credentials.

Create a secret with the values for the following parameters:

Parameter	Description
`KeyVersionResourceID`	Unique resource path that displays the key version resource ID for your Google Cloud KMS.
`ServiceAccountKey`	JSON file that contains the Google Cloud KMS credentials from your Google Cloud account. IMPORTANT: You must format the JSON object properly. Ensure you properly indent the credential fields within the file.

The following example shows the contents of a ServiceAccountKey JSON file:

{
  "type": "service_account",
  "project_id": "my-project-common-0",
  "private_key_id": "e120598ea4f88249469fcdd75a9a785c1bb3\",
  "private_key": "-----BEGIN PRIVATE KEY-----\\nMIIEuwIBA(truncated)SfecnS0mT94D9\\n-----END PRIVATE KEY-----\\n\",
  "client_email": "my-email-kms-0@my-project-common-0.iam.gserviceaccount.com\",
  "client_id": "10180967717292066",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://accounts.google.com/o/oauth2/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/my-email-kms-0%40my-project-common-0.iam.gserviceaccount.com"
  "universe_domain": "googleapis.com"
}

To create and label a secret, run the following commands with your Google Cloud credentials:

kubectl create secret generic azure-ear-creds \
  --from-literal="KeyVersionResourceID=<resource-id>" \
  --from-file="ServiceAccountKey=<your-service-account-key-files.json>" \
  -n mongodb-atlas-system

kubectl label secret gcp-ear-creds atlas.mongodb.com/type=credentials -n mongodb-atlas-system

Specify the `spec.encryptionAtRest.googleCloudKms` parameter.

Add the spec.encryptionAtRest.googleCloudKms object to the spec.encryptionAtRest array in the AtlasProject Custom Resource, including the following parameters:

Parameter	Description
`spec.encryptionAtRest.googleCloudKms.enabled`	Flag that indicates whether this project uses Google Cloud KMS to encrypt data at rest. To enable encryption at rest using Google Cloud KMS, set this parameter to `true`. To disable encryption at rest using Google Cloud KMS, set this parameter to `false`. If you disable encryption at rest using Google Cloud KMS, Atlas Kubernetes Operator removes the configuration details.
`spec.encryptionAtRest.googleCloudKms.secretRef.name`	Name of the secret that contains your Google Cloud credentials.
`spec.encryptionAtRest.googleCloudKms.secretRef.namespace`	Namespace that contains your Google Cloud credentials. If unspecified, this parameter defaults to the namespace of the `AtlasProject` custom resource.

You must use a secret that contains the values for KeyVersionResourceID and ServiceAccountKey.

Run the following command:

cat <<EOF | kubectl apply -f -
apiVersion: atlas.mongodb.com/v1
kind: AtlasProject
metadata:
  name: my-project
spec:
  name: Test Atlas Operator Project
  encryptionAtRest:
    googleCloudKms:
      enabled: true
      secretRef:
        name: gcp-ear-creds
        namespace: mongodb-atlas-system
EOF

Check for successful enablement of encryption at rest on your project.

Run the following command to check whether Atlas Kubernetes Operator detects the Google Cloud KMS configuration for your project.

kubectl get atlasprojects my-project -o=jsonpath='{.status.conditions[?(@.type=="EncryptionAtRestReadyType")].status}

true

Enable encryption at rest using customer-managed keys for your cluster.

After you enable encryption at rest using customer-managed keys for your project, you must enable it at the cluster level to encrypt data.

Run the following command to add the spec.deploymentSpec.encryptionAtRestProvider to your AtlasDeployment Custom Resource, which enables encryption at rest using your Google Cloud key for this cluster:

cat <<EOF | kubectl apply -f -
      apiVersion: atlas.mongodb.com/v1
      kind: AtlasDeployment
      metadata:
        name: my-cluster
      spec:
        name: Test Atlas Operator Cluster
        DeploymentSpec:
          encryptionAtRestProvider: "GCP"
      EOF

Back

X.509

Federated Authentication

Important

Feature unavailable in Serverless Instances

Note

Prerequisites

Important

Procedure

Create a secret with your AWS credentials.

Specify the spec.encryptionAtRest.awsKms parameter.

Check for successful enablement of encryption at rest on your project.

Enable encryption at rest using customer-managed keys for your cluster.

Create a secret with your Azure credentials.

Specify the spec.encryptionAtRest.azureKeyVault parameter.

Check for successful enablement of encryption at rest on your project.

Enable encryption at rest using customer-managed keys for your cluster.

Create a secret with your Google Cloud credentials.

Specify the spec.encryptionAtRest.googleCloudKms parameter.

Check for successful enablement of encryption at rest on your project.

Enable encryption at rest using customer-managed keys for your cluster.

Specify the `spec.encryptionAtRest.awsKms` parameter.

Specify the `spec.encryptionAtRest.azureKeyVault` parameter.

Specify the `spec.encryptionAtRest.googleCloudKms` parameter.