INTMDB-153: Create 0.8.0-upgrade-guide.html.markdown (#384)

* Create 0.8.0-upgrade-guide.html.markdown Guide for IAM creds/roles switch needs and private link deprecation * Update 0.8.0-upgrade-guide.html.markdown Fixes from PR review * Update 0.8.0-upgrade-guide.html.markdown * Update 0.8.0-upgrade-guide.html.markdown adjustment to import statement
mongodb · Jan 20, 2021 · b44afaa · b44afaa
1 parent 080d3b2
commit b44afaa
Showing 1 changed file with 150 additions and 0 deletions.
diff --git a/website/docs/guides/0.8.0-upgrade-guide.html.markdown b/website/docs/guides/0.8.0-upgrade-guide.html.markdown
@@ -0,0 +1,150 @@
+---
+layout: "mongodbatlas"
+page_title: "MongoDB Atlas Provider 0.8.0: Upgrade and Information Guide"
+sidebar_current: "docs-mongodbatlas-guides-080-upgrade-guide"
+description: |-
+    MongoDB Atlas Provider 0.8.0: Upgrade and Information Guide
+    
+---
+
+# MongoDB Atlas Provider v0.8.0: Upgrade and Information Guide
+
+Besides the bug fixes, improvements and enhancements listed in the [CHANGELOG](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CHANGELOG.md) for 0.8.0 we want to call out some important changes and information that you should be aware of before upgrading to this newest provider.
+
+## Support for the switch from AWS credentials-based access (IAM user) to role-based access (IAM role) w/ Customer Key Management with AWS KMS
+
+MongoDB Atlas now supports IAM roles for use with AWS services.   Current users who had programmatically managed AWS KMS encryption keys for encryption at rest in the past 60 days were notified by email.  The MongoDB Atlas Provider v0.8.0 includes the support needed to use IAM roles (and transition from using IAM user).
+
+### Step 1: Configuring Cloud Provider Access
+
+If you programmatically create new Atlas projects and use AWS KMS encryption keys for encryption at rest or you are ready to switch an existing Atlas project using AWS KMS encryption keys for encryption at rest to using IAM users to roles, you will need to first configure the [cloud provider access](https://docs.atlas.mongodb.com/security/set-up-unified-aws-access) with https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cloud_provider_access.  The Atlas documentation for [cloud provider access](https://docs.atlas.mongodb.com/security/set-up-unified-aws-access) will walk you through the process in general.  
+
+Configuring cloud provider access with Terraform is a multi step process:
+
+1) Configure and apply the Atlas cloud_provide_access resource
+2) modify your AWS IAM role trust policy with AWS
+3) Add the IAM Assumed Role ARN to your Atlas resource definition
+4) Apply again to authorize.
+
+After this process you can then configure or update encryption at rest for your project.  For example:
+
+Example 1st Terraform Apply
+
+```hcl
+    resource "mongodbatlas_cloud_provider_access" "test" {
+        project_id = mongodbatlas_project.my_project.id
+        provider_name = "AWS"
+        #after first apply update below with the iam assumed role arn after editing the policy
+        #iam_assumed_role_arn = "REPLACE_WITH_iam_assumed_role_arn"
+    }
+    #Information you’ll need to edit your AWS policy 
+        output "cloud_provider_access_external_id" {
+        value = mongodbatlas_cloud_provider_access.test.atlas_assumed_role_external_id
+    }
+    #Information you’ll need to edit your AWS policy 
+        output "cloud_provider_access_arn" {
+        value = mongodbatlas_cloud_provider_access.test.atlas_aws_account_arn
+    }
+    #Information you’ll need to enable BYOK encryption at rest later        
+        output "cloud_provider_role_id" {
+        value = mongodbatlas_cloud_provider_access.test.role_id
+    }
+```
+
+Example 2nd Apply
+
+```hcl
+    resource "mongodbatlas_cloud_provider_access" "test" {
+        project_id = mongodbatlas_project.my_project.id
+        provider_name = "AWS"
+        #after first apply update below with the iam assumed role arn after editing the policy
+        iam_assumed_role_arn = "REPLACE_WITH_iam_assumed_role_arn"
+    }
+    #Information you’ll need to edit your AWS policy 
+        output "cloud_provider_access_external_id" {
+        value = mongodbatlas_cloud_provider_access.test.atlas_assumed_role_external_id
+    }
+    #Information you’ll need to edit your AWS policy 
+        output "cloud_provider_access_arn" {
+        value = mongodbatlas_cloud_provider_access.test.atlas_aws_account_arn
+    }
+    #Information you’ll need to enable BYOK encryption at rest later        
+    output "cloud_provider_role_id" {
+        value = mongodbatlas_cloud_provider_access.test.role_id
+    }
+```
+
+### Step 2: Configuring Customer Key Management with AWS KMS
+
+**If the project is new** and will have Customer Key Management with AWS KMS you simply need to configure the encryption_at_rest Terraform resource to use an IAM role as in the documentation examples, for example (these are example values, replace with your values):
+
+```hcl
+    aws_kms = {
+        enabled                               = true
+        #value from output above
+        role_id                          = "5f232b94af0a6b41747akx2d"
+        customer_master_key_id         = "030gce02-586d-48d2-a999-05ea954fdd0g"
+        region                             = "US_EAST_1"
+    }
+```
+
+**If the project exists** already and is using Customer Key Management with AWS KMS then you can update the encryption_at_rest Terraform resource to use the new IAM role: https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/encryption_at_rest
+
+**IMPORTANT!!!  If you switch your Atlas project from credentials-based access (IAM user) to role-based access (IAM role) to your encryption keys, you cannot undo the role-based access configuration and revert to credentials-based access for that project.**
+
+For example (these are example values, replace with your values) within the mongodbatlas_encryption_at_rest resource:
+
+Existing:
+
+```hcl
+    aws_kms = {
+        enabled                               = true
+        access_key_id                  = "AKIAIOSFUDNN9EXAMPLE"
+        secret_access_key           = "wJalrXUtnFRTI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+        customer_master_key_id         = "030gce02-586d-48d2-a999-05ea954fdd0g"
+        region                             = "US_EAST_1"
+      }
+```
+
+New:
+
+```hcl
+    aws_kms = {
+        enabled                               = true
+        role_id                          = "5f232b94af0a6b41747akx2d"
+        customer_master_key_id         = "030gce02-586d-48d2-a999-05ea954fdd0g"
+        region                             = "US_EAST_1"
+      }
+```
+
+## Addition of Azure Private Link
+
+One of the new features in Atlas that the MongoDB Atlas provider v0.8.0 supports is [Azure Private Link](https://docs.atlas.mongodb.com/security-private-endpoint).
+This can be setup using two new resources: [privatelink_endpoint](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint) and [privatelink_endpoint_service]
+(https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint_service)
+
+### Deprecation of AWS PrivateLink Only Provider Resources private_endpoint and private_endpoint_interface_link
+
+With this addition of Azure Private Link the Atlas team has now deprecated the [previous AWS only resource](https://docs.atlas.mongodb.com/reference/api/private-endpoint-create-one-private-endpoint-connection) in the Atlas API and replaced it with a new [API resource](https://docs.atlas.mongodb.com/reference/api/private-endpoints-endpoint-create-one) that supports both AWS and Azure.  In order to follow this improvement the MongoDB Atlas provider resources private_endpoint and private_endpoint_interface_link are also now deprecated.  We encourage users of these resources to move to the new resources: [privatelink_endpoint](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint) and [privatelink_endpoint_service](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint_service) as soon as possible.
+
+In order to transition from the deprecated resources to the new without disabling private link you will need to:
+
+1) [Remove](https://www.terraform.io/docs/commands/state/rm.html) any currently managed private_endpoint and private_endpoint_interface_link resources from your Terraform state.  We suggest saving the state information before making any changes both in case of mistake and to use for the next steps.
+2) Create a new resource in your Terraform configuration file using the documentation as a guide: [privatelink_endpoint](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint) and [privatelink_endpoint_service](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint_service)
+3) Then [import](https://www.terraform.io/docs/commands/import.html) the privatelink information into the new resources, e.g:
+
+```hcl
+terraform import mongodbatlas_privatelink_endpoint.test {project_id}-{private_link_id}-{provider_name}
+
+terraform import mongodbatlas_privatelink_endpoint_service.test {project_id}--{private_link_id}--{endpoint_service_id}--{provider_name}
+```
+
+NOTE: Provider name for both resources are case sensitive.
+
+### Helpful Links
+
+* [Report bugs](https://github.com/mongodb/terraform-provider-mongodbatlas/issues)
+
+* [Request Features](https://feedback.mongodb.com/forums/924145-atlas?category_id=370723)
+
+* [Contact Support](https://docs.atlas.mongodb.com/support/) covered by MongoDB Atlas support plans, Developer and above.