(DOCSP-46242): Add BYOK Encryption examples (#76)

* initial draft

* add link to complete examples

* update structure, add context

Author: davidhou17

source/data-encryption.txt

@@ -38,6 +38,8 @@ OpenSSL :abbr:`FIPS (Federal Information Processing Standards)` Object Module.
    :figwidth: 750px
    :alt: An image showing encryption in transit with TLS between client applications and MongoDB Atlas.
 
+.. _arch-center-encryption-at-rest:
+
 Encryption at Rest
 ~~~~~~~~~~~~~~~~~~
 
@@ -49,17 +51,17 @@ disk encryption, with the provider managing the encryption keys.
 This process cannot be disabled.
 
 Additionally, you have the option to enable database-level encryption
-by "bringing your own key" (BYOK) with a key management service (KMS).
+by **"bringing your own key" (BYOK)** with a key management service (KMS)
+such as AWS KMS, Google Cloud KMS, or Azure Key Vault.
 |byok| encryption adds another layer of security for additional
 confidentiality and data segmentation:
 
 .. figure:: /includes/images/byok-encryption.svg
    :figwidth: 750px
    :alt: An image showing encryption at rest with an additional customer-managed key.
 
-To learn more about using your own encryption keys with 
-AWS Key Management Service (KMS), Google Cloud KMS, or 
-Azure Key Vault, see :ref:`security-kms-encryption`.
+To learn more about using your own encryption keys
+with a key management service (KMS), see :ref:`security-kms-encryption`.
 
 Encryption in Use
 ~~~~~~~~~~~~~~~~~
@@ -128,19 +130,22 @@ Recommendations for Data Encryption
 Consider the following security recommendations when 
 provisioning your {+clusters+}.
 
+.. _arch-center-byok:
+
 BYOK Encryption
 ~~~~~~~~~~~~~~~
 
-For staging and production environments, we recommend that you enable :ref:`BYOK
-encryption <security-kms-encryption>` through AWS Key Management Service (KMS), 
-Google Cloud KMS, or Azure Key Vault when provisioning your {+clusters+} 
-to avoid relying on application development teams to configure it later on. 
-This also ensures consistent data protection across your environments.
+.. include:: /includes/byok-encryption-recommendations.rst
+
+Use the following methods to enable |byok| encryption:
+
+- :atlas:`{+atlas-ui+} </security-kms-encryption>`
+- :oas-atlas-tag:`{+atlas-admin-api+} </Encryption-at-Rest-using-Customer-Key-Management>`
+- `Terraform <https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/encryption_at_rest>`__
 
-For development and testing environments, consider skipping |byok| encryption
-to save costs. However, if you're storing sensitive data in |service|, 
-such as for healthcare or financial services industries, consider enabling 
-|byok| encryption in development and testing environments as well.
+To learn how to configure |byok| encryption
+when provisioning a new |service| organization, project, and {+cluster+},
+see :ref:`arch-center-create-hierarchy-example`.
 
 Data Classification
 ~~~~~~~~~~~~~~~~~~~

source/hierarchy.txt

@@ -78,6 +78,8 @@ security settings and governance for your {+service+} enterprise estate:
    :align: center
    :lightbox:
 
+.. _arch-center-recommendations:
+
 Recommendations
 ~~~~~~~~~~~~~~~
 
@@ -114,7 +116,15 @@ projects and {+clusters+}:
      - The back end for your application that is live for your
        end users.
 
-For your dev and test environments, you can develop {+service+}
+BYOK Encryption
+```````````````
+
+.. include:: /includes/byok-encryption-recommendations.rst
+
+Local {+service+} Deployments
+`````````````````````````````
+
+For your dev and test environments, you can also develop {+service+}
 {+clusters+} locally with the {+atlas-cli+}. This can enable developers
 to work locally from their machine and cut down on costs for
 development and test environments. To learn more, see 
@@ -314,6 +324,8 @@ them, see the {+service+} documentation for each cloud provider:
 - :atlas:`Azure </reference/microsoft-azure/>`
 - :atlas:`{+gcp+} </reference/google-gcp/>`
 
+.. _arch-center-create-hierarchy-example:
+
 Examples
 --------
 
@@ -384,6 +396,17 @@ These examples also apply other recommended configurations, including:
 
       - :ref:`atlas-projects-list`
 
+      Configure BYOK Encryption
+      ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+      .. include:: /includes/byok-encryption-recommendations-short.rst
+
+      You can't manage |byok| encryption with the {+atlas-cli+}. 
+      Use the following methods to configure |byok| encryption:
+
+      - :atlas:`{+atlas-ui+} </security-kms-encryption>`
+      - :oas-atlas-tag:`{+atlas-admin-api+} </Encryption-at-Rest-using-Customer-Key-Management>`
+
       Create One {+Cluster+} Per Project
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -415,7 +438,7 @@ These examples also apply other recommended configurations, including:
       see :ref:`atlas-clusters-create`.
 
    .. tab:: Terraform
-      :tabid: Terraform
+      :tabid: tf
 
       .. note::
 
@@ -468,29 +491,6 @@ These examples also apply other recommended configurations, including:
 
             .. include:: /includes/examples/tf-example-provider.rst
 
-            After you create the files, navigate to each application and environment pair's directory and run the following
-            command to initialize Terraform:
-
-            .. code-block::
-
-               terraform init
-
-            Run the following command to view the Terraform plan:
-
-            .. code-block::
-
-               terraform plan
-            
-            Run the following command to create one project and one deployment for the application and environment pair. The command uses the files and the |service-terraform| to
-            create the projects and clusters:
-
-            .. code-block::
-
-               terraform apply
-
-            When prompted, type ``yes`` and press :kbd:`Enter` to apply
-            the configuration.
-
          .. tab:: Staging and Prod Environments
             :tabid: stagingprod
 
@@ -518,33 +518,92 @@ These examples also apply other recommended configurations, including:
             ```````````
 
             .. include:: /includes/examples/tf-example-provider.rst
+      
+      For more configuration options and info about this example, 
+      see |service-terraform| and the `MongoDB Terraform Blog Post
+      <https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-terraform-aws/>`__.
 
-            After you create the files, navigate to each application and environment pair's directory and run the following
-            command to initialize Terraform:
+      Configure BYOK Encryption
+      ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-            .. code-block::
+      .. tabs::
 
-               terraform init
+         .. tab:: Dev and Test Environments
+            :tabid: devtest
 
-            Run the following command to view the Terraform plan:
+            For your development and testing environments, consider skipping |byok| encryption 
+            environments to save costs, unless you're in a highly-regulated industry
+            or storing sensitive data. To learn more, see :ref:`arch-center-recommendations`.
 
-            .. code-block::
+         .. tab:: Staging and Prod Environments
+            :tabid: stagingprod
 
-               terraform plan
-            
-            Run the following command to create one project and one deployment for the application and environment pair. The command uses the files and the |service-terraform| to
-            create the projects and clusters:
+            For your staging and production environments environments, we
+            recommend enabling |byok| encryption when provisioning your {+clusters+}.
+            To learn more, see :ref:`arch-center-recommendations`.
 
-            .. code-block::
+      To enable |byok| encryption with Terraform, 
+      create the following resources. Change the IDs and names to use your values:
 
-               terraform apply
+      .. tabs::
+         
+         .. tab:: AWS
+            :tabid: aws
+
+            .. tip:: 
+
+               For a complete configuration example, see
+               :github:`Atlas Terraform Provider Example <mongodb/terraform-provider-mongodbatlas/blob/master/examples/mongodbatlas_encryption_at_rest/aws/atlas-cluster>`.
+
+               Alternatively, to simplify the configuration process, you can use the
+               `encryption at rest Terraform module <https://registry.terraform.io/modules/terraform-mongodbatlas-modules/encryption-at-rest/mongodbatlas/latest>`__.
+
+            .. include:: /includes/examples/tf-example-byok-aws.rst
+         
+         .. tab:: Azure
+            :tabid: azure
+
+            .. tip:: 
+
+               For a complete configuration example, see
+               :github:`Atlas Terraform Provider Example <mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest/azure>`.
 
-            When prompted, type ``yes`` and press :kbd:`Enter` to apply
-            the configuration. 
+            .. include:: /includes/examples/tf-example-byok-azure.rst
+         
+         .. tab:: GCP
+            :tabid: gcp
+
+            .. include:: /includes/examples/tf-example-byok-gcp.rst
 
       For more configuration options and info about this example, 
-      see |service-terraform| and the `MongoDB Terraform Blog Post
-      <https://www.mongodb.com/developer/products/atlas/deploy-mongodb-atlas-terraform-aws/>`__.
+      see `Terraform documentation 
+      <https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/encryption_at_rest>`__.
+
+      Create the Projects and Deployments
+      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+      After you create the files, navigate to each application and environment pair's directory and run the following
+      command to initialize Terraform:
+
+      .. code-block::
+
+         terraform init
+
+      Run the following command to view the Terraform plan:
+
+      .. code-block::
+
+         terraform plan
+      
+      Run the following command to create one project and one deployment for the application and environment pair. The command uses the files and the |service-terraform| to
+      create the projects and clusters:
+
+      .. code-block::
+
+         terraform apply
+
+      When prompted, type ``yes`` and press :kbd:`Enter` to apply
+      the configuration. 
 
 Next Steps
 ----------

source/includes/byok-encryption-recommendations-short.rst

@@ -0,0 +1,5 @@
+For staging and production environments, we
+recommend enabling |byok| encryption when provisioning your {+clusters+}.
+For development and testing, consider skipping |byok| encryption 
+environments to save costs, unless you're in a highly-regulated industry
+or storing sensitive data. To learn more, see :ref:`arch-center-recommendations`.

source/includes/byok-encryption-recommendations.rst

@@ -0,0 +1,13 @@
+
+You enable :ref:`BYOK encryption <arch-center-encryption-at-rest>` at the project level. 
+Once enabled, it automatically applies to all {+clusters+} created within the project, 
+ensuring consistent data protection across your environment.
+
+For **staging and production environments**, we recommend that you 
+enable |byok| encryption when provisioning your {+clusters+} 
+to avoid relying on application development teams to configure it later on.
+
+For **development and testing environments**, consider skipping |byok| encryption
+to save costs. However, if you're storing sensitive data in |service|, 
+such as for healthcare or financial services industries, consider enabling 
+|byok| encryption in development and testing environments as well.

source/includes/examples/tf-example-byok-aws.rst

@@ -0,0 +1,36 @@
+.. code-block:: 
+   :copyable: true
+
+   resource "mongodbatlas_cloud_provider_access_setup" "setup_only" {
+     project_id    = var.atlas_project_id
+     provider_name = "AWS"
+   }
+
+   resource "mongodbatlas_cloud_provider_access_authorization" "auth_role" {
+     project_id = var.atlas_project_id
+     role_id    = mongodbatlas_cloud_provider_access_setup.setup_only.role_id
+
+     aws {
+       iam_assumed_role_arn = aws_iam_role.test_role.arn
+     }
+   }
+
+   resource "mongodbatlas_encryption_at_rest" "test" {
+     project_id = var.atlas_project_id
+
+     aws_kms_config {
+       enabled                = true
+       customer_master_key_id = aws_kms_key.kms_key.id
+       region                 = var.atlas_region
+       role_id                = mongodbatlas_cloud_provider_access_authorization.auth_role.role_id
+     }
+   }
+
+   data "mongodbatlas_encryption_at_rest" "test" {
+     project_id = mongodbatlas_encryption_at_rest.test.project_id
+   }
+
+   output "is_aws_kms_encryption_at_rest_valid" {
+     value = data.mongodbatlas_encryption_at_rest.test.aws_kms_config.valid
+   }
+   

source/includes/examples/tf-example-byok-azure.rst

@@ -0,0 +1,29 @@
+.. code-block:: 
+   :copyable: true
+
+   resource "mongodbatlas_encryption_at_rest" "test" {
+    project_id = var.atlas_project_id
+  
+    azure_key_vault_config {
+      enabled           = true
+      azure_environment = "AZURE"
+  
+      tenant_id       = var.azure_tenant_id
+      subscription_id = var.azure_subscription_id
+      client_id       = var.azure_client_id
+      secret          = var.azure_client_secret
+  
+      resource_group_name = var.azure_resource_group_name
+      key_vault_name      = var.azure_key_vault_name
+      key_identifier      = var.azure_key_identifier
+    }
+  }
+  
+  data "mongodbatlas_encryption_at_rest" "test" {
+    project_id = mongodbatlas_encryption_at_rest.test.project_id
+  }
+  
+  output "is_azure_encryption_at_rest_valid" {
+    value = data.mongodbatlas_encryption_at_rest.test.azure_key_vault_config.valid
+  }
+  

source/includes/examples/tf-example-byok-gcp.rst

@@ -0,0 +1,13 @@
+.. code-block:: 
+   :copyable: true
+
+   resource "mongodbatlas_encryption_at_rest" "test" {
+     project_id = var.atlas_project_id
+
+     google_cloud_kms_config {
+       enabled                 = true
+       service_account_key     = "{\"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\": \"[email protected]\",\"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\"}"
+       key_version_resource_id = "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
+     }
+   }
+   

source/includes/shared-settings-clusters-stagingprod.rst

@@ -1,6 +1,7 @@
 - Cluster tier set to ``M30`` for a medium-sized application. Use the
   :ref:`cluster size guide <arch-center-cluster-size-guide>` to learn
   the recommended cluster tier for your application size.
+- Encryption at rest with customer-managed keys (|byok|) enabled.
 
 Our examples use |aws|, |azure|, and {+gcp+}
 interchangeably. You can use any of these three cloud providers, but