Skip to content

Commit b44afaa

Browse files
themantissathemantissa
authored
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
1 parent 080d3b2 commit b44afaa

File tree

1 file changed

+150
-0
lines changed

1 file changed

+150
-0
lines changed

‎website/docs/guides/0.8.0-upgrade-guide.html.markdown‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
layout: "mongodbatlas"
3+
page_title: "MongoDB Atlas Provider 0.8.0: Upgrade and Information Guide"
4+
sidebar_current: "docs-mongodbatlas-guides-080-upgrade-guide"
5+
description: |-
6+
MongoDB Atlas Provider 0.8.0: Upgrade and Information Guide
7+
8+
---
9+
10+
# MongoDB Atlas Provider v0.8.0: Upgrade and Information Guide
11+
12+
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.
13+
14+
## Support for the switch from AWS credentials-based access (IAM user) to role-based access (IAM role) w/ Customer Key Management with AWS KMS
15+
16+
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).
17+
18+
### Step 1: Configuring Cloud Provider Access
19+
20+
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.
21+
22+
Configuring cloud provider access with Terraform is a multi step process:
23+
24+
1) Configure and apply the Atlas cloud_provide_access resource
25+
2) modify your AWS IAM role trust policy with AWS
26+
3) Add the IAM Assumed Role ARN to your Atlas resource definition
27+
4) Apply again to authorize.
28+
29+
After this process you can then configure or update encryption at rest for your project. For example:
30+
31+
Example 1st Terraform Apply
32+
33+
```hcl
34+
resource "mongodbatlas_cloud_provider_access" "test" {
35+
project_id = mongodbatlas_project.my_project.id
36+
provider_name = "AWS"
37+
#after first apply update below with the iam assumed role arn after editing the policy
38+
#iam_assumed_role_arn = "REPLACE_WITH_iam_assumed_role_arn"
39+
}
40+
#Information you’ll need to edit your AWS policy
41+
output "cloud_provider_access_external_id" {
42+
value = mongodbatlas_cloud_provider_access.test.atlas_assumed_role_external_id
43+
}
44+
#Information you’ll need to edit your AWS policy
45+
output "cloud_provider_access_arn" {
46+
value = mongodbatlas_cloud_provider_access.test.atlas_aws_account_arn
47+
}
48+
#Information you’ll need to enable BYOK encryption at rest later
49+
output "cloud_provider_role_id" {
50+
value = mongodbatlas_cloud_provider_access.test.role_id
51+
}
52+
```
53+
54+
Example 2nd Apply
55+
56+
```hcl
57+
resource "mongodbatlas_cloud_provider_access" "test" {
58+
project_id = mongodbatlas_project.my_project.id
59+
provider_name = "AWS"
60+
#after first apply update below with the iam assumed role arn after editing the policy
61+
iam_assumed_role_arn = "REPLACE_WITH_iam_assumed_role_arn"
62+
}
63+
#Information you’ll need to edit your AWS policy
64+
output "cloud_provider_access_external_id" {
65+
value = mongodbatlas_cloud_provider_access.test.atlas_assumed_role_external_id
66+
}
67+
#Information you’ll need to edit your AWS policy
68+
output "cloud_provider_access_arn" {
69+
value = mongodbatlas_cloud_provider_access.test.atlas_aws_account_arn
70+
}
71+
#Information you’ll need to enable BYOK encryption at rest later
72+
output "cloud_provider_role_id" {
73+
value = mongodbatlas_cloud_provider_access.test.role_id
74+
}
75+
```
76+
77+
### Step 2: Configuring Customer Key Management with AWS KMS
78+
79+
**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):
80+
81+
```hcl
82+
aws_kms = {
83+
enabled = true
84+
#value from output above
85+
role_id = "5f232b94af0a6b41747akx2d"
86+
customer_master_key_id = "030gce02-586d-48d2-a999-05ea954fdd0g"
87+
region = "US_EAST_1"
88+
}
89+
```
90+
91+
**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
92+
93+
**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.**
94+
95+
For example (these are example values, replace with your values) within the mongodbatlas_encryption_at_rest resource:
96+
97+
Existing:
98+
99+
```hcl
100+
aws_kms = {
101+
enabled = true
102+
access_key_id = "AKIAIOSFUDNN9EXAMPLE"
103+
secret_access_key = "wJalrXUtnFRTI/K7MDENG/bPxRfiCYEXAMPLEKEY"
104+
customer_master_key_id = "030gce02-586d-48d2-a999-05ea954fdd0g"
105+
region = "US_EAST_1"
106+
}
107+
```
108+
109+
New:
110+
111+
```hcl
112+
aws_kms = {
113+
enabled = true
114+
role_id = "5f232b94af0a6b41747akx2d"
115+
customer_master_key_id = "030gce02-586d-48d2-a999-05ea954fdd0g"
116+
region = "US_EAST_1"
117+
}
118+
```
119+
120+
## Addition of Azure Private Link
121+
122+
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).
123+
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]
124+
(https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/privatelink_endpoint_service)
125+
126+
### Deprecation of AWS PrivateLink Only Provider Resources private_endpoint and private_endpoint_interface_link
127+
128+
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.
129+
130+
In order to transition from the deprecated resources to the new without disabling private link you will need to:
131+
132+
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.
133+
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)
134+
3) Then [import](https://www.terraform.io/docs/commands/import.html) the privatelink information into the new resources, e.g:
135+
136+
```hcl
137+
terraform import mongodbatlas_privatelink_endpoint.test {project_id}-{private_link_id}-{provider_name}
138+
139+
terraform import mongodbatlas_privatelink_endpoint_service.test {project_id}--{private_link_id}--{endpoint_service_id}--{provider_name}
140+
```
141+
142+
NOTE: Provider name for both resources are case sensitive.
143+
144+
### Helpful Links
145+
146+
* [Report bugs](https://github.com/mongodb/terraform-provider-mongodbatlas/issues)
147+
148+
* [Request Features](https://feedback.mongodb.com/forums/924145-atlas?category_id=370723)
149+
150+
* [Contact Support](https://docs.atlas.mongodb.com/support/) covered by MongoDB Atlas support plans, Developer and above.

0 commit comments

Comments
 (0)