Skip to content

Commit 2d5daf0

Browse files
AgustinBettatiAgustinBettati
authored
doc: Add migration guide for Encryption at Rest (GCP) Service Account JSON to Role-based Auth (#3656)
* add migration guide * mention migration guide in resource docs * rename test to this * applying docs feedback * Adding note on one-way transition
1 parent 3edd307 commit 2d5daf0

File tree

3 files changed

+153
-2
lines changed

3 files changed

+153
-2
lines changed

‎docs/guides/encryption-at-rest-gcp-role-based-migration.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
page_title: "Migration Guide: Encryption at Rest (GCP) Service Account JSON to Role-based Auth"
3+
---
4+
5+
# Migration Guide: Encryption at Rest (GCP) Service Account JSON to Role-based Auth
6+
7+
**Objective**: Migrate from using a static Service Account JSON key in `mongodbatlas_encryption_at_rest.google_cloud_kms_config.service_account_key` to role-based authentication using an Atlas-managed service account via `mongodbatlas_encryption_at_rest.google_cloud_kms_config.role_id`.
8+
9+
**Note**: Once migrated to using role-based authentication, it is not possible to revert back to using a static Service Account JSON key.
10+
11+
## Best Practices Before Migrating
12+
- Test the migration in a non-production environment if possible.
13+
14+
## Migration Steps
15+
16+
### Current (using Service Account JSON key)
17+
18+
This configuration serves as the starting point for the migration.
19+
20+
```hcl
21+
resource "mongodbatlas_encryption_at_rest" "this" {
22+
project_id = var.atlas_project_id
23+
24+
google_cloud_kms_config {
25+
enabled = true
26+
service_account_key = "{\"type\": \"service_account\",\"project_id\": \"my-project-common-0\", ...}"
27+
key_version_resource_id = "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
28+
}
29+
}
30+
```
31+
32+
### 1) Obtain the Atlas-managed GCP service account
33+
Add the following resources to enable Atlas Cloud Provider Access for GCP and authorize it for your project:
34+
35+
```hcl
36+
resource "mongodbatlas_cloud_provider_access_setup" "this" {
37+
project_id = var.atlas_project_id
38+
provider_name = "GCP"
39+
}
40+
41+
resource "mongodbatlas_cloud_provider_access_authorization" "this" {
42+
project_id = var.atlas_project_id
43+
role_id = mongodbatlas_cloud_provider_access_setup.this.role_id
44+
}
45+
```
46+
47+
The computed attribute `mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas` contains the email address of the Google Service Account managed by Atlas.
48+
49+
### 2) Grant KMS permissions to the Atlas service account
50+
51+
If your KMS key is managed with Terraform, IAM bindings can be granted with the following GCP resources:
52+
53+
```hcl
54+
# IAM Binding: Grant 'cryptoKeyEncrypterDecrypter' role
55+
resource "google_kms_crypto_key_iam_binding" "encrypter_decrypter_binding" {
56+
crypto_key_id = google_kms_crypto_key.crypto_key.id
57+
role = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
58+
59+
members = [
60+
"serviceAccount:${mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas}"
61+
]
62+
}
63+
64+
# IAM Binding: Grant 'viewer' role
65+
resource "google_kms_crypto_key_iam_binding" "viewer_binding" {
66+
crypto_key_id = google_kms_crypto_key.crypto_key.id
67+
role = "roles/cloudkms.viewer"
68+
69+
members = [
70+
"serviceAccount:${mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas}"
71+
]
72+
}
73+
```
74+
75+
Alternatively, you can use Google Cloud CLI:
76+
77+
```shell
78+
gcloud kms keys add-iam-policy-binding \
79+
<key-name> \
80+
--location <location> \
81+
--keyring <keyring-name> \
82+
--member <ATLAS_OWNED_SERVICE_ACCOUNT_EMAIL> \
83+
--role="roles/cloudkms.cryptoKeyEncrypterDecrypter"
84+
85+
gcloud kms keys add-iam-policy-binding \
86+
<key-name> \
87+
--location <location> \
88+
--keyring <keyring-name> \
89+
--member <ATLAS_OWNED_SERVICE_ACCOUNT_EMAIL> \
90+
--role="roles/cloudkms.viewer"
91+
```
92+
93+
### 3) Update the Encryption at Rest resource to use role-based auth
94+
95+
Replace the `service_account_key` with `role_id` using the value from the authorization resource:
96+
97+
```hcl
98+
resource "mongodbatlas_encryption_at_rest" "this" {
99+
project_id = var.atlas_project_id
100+
101+
google_cloud_kms_config {
102+
enabled = true
103+
key_version_resource_id = "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
104+
role_id = mongodbatlas_cloud_provider_access_authorization.this.role_id
105+
}
106+
}
107+
```
108+
109+
**Note:** If you grant KMS IAM bindings within the same apply, you must add a `depends_on` block to `mongodbatlas_encryption_at_rest`. This ensures Terraform configures the bindings before it configures the role in the `mongodbatlas_encryption_at_rest` resource.
110+
111+
```
112+
resource "mongodbatlas_encryption_at_rest" "this" {
113+
...
114+
115+
depends_on = [
116+
google_kms_crypto_key_iam_binding.encrypter_decrypter_binding,
117+
google_kms_crypto_key_iam_binding.viewer_binding
118+
]
119+
}
120+
121+
```
122+
123+
124+
Running `terraform plan` should show a change similar to:
125+
126+
```
127+
# mongodbatlas_encryption_at_rest.test will be updated in-place
128+
~ resource "mongodbatlas_encryption_at_rest" "this" {
129+
id = "66d6d2bdb181f8665222509b"
130+
# (2 unchanged attributes hidden)
131+
132+
~ google_cloud_kms_config {
133+
+ role_id = "68b0448ac59ddc0496f95fa5"
134+
- service_account_key = (sensitive value) -> null
135+
~ valid = true -> (known after apply)
136+
# (2 unchanged attributes hidden)
137+
}
138+
}
139+
```
140+
141+
### 4) Apply the changes
142+
143+
Run `terraform apply` to complete the migration. Once applied, the migration is complete.
144+
145+
## Additional Resources
146+
- Complete role-based auth example that includes GCP KMS resource creation and IAM binding setup: [examples/mongodbatlas_encryption_at_rest/gcp](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest/gcp)
147+

‎docs/resources/encryption_at_rest.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,9 @@ Please review the [`mongodbatlas_encryption_at_rest_private_endpoint` resource d
134134

135135

136136
### Configuring encryption at rest using customer key management in GCP
137-
For GCP environments using static service account key, we recommend configuring encryption at rest with customer key management. This approach uses role-based authentication through Cloud Provider Access for a more secure solution
137+
For GCP environments using static service account key, we recommend configuring encryption at rest with customer key management. For more details see our [Migration Guide: Encryption at Rest (GCP) Service Account JSON to Role-based Auth](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/encryption-at-rest-gcp-role-based-migration).
138+
139+
This approach uses role-based authentication through Cloud Provider Access for a more secure solution.
138140

139141
```terraform
140142
resource "mongodbatlas_cloud_provider_access_setup" "this" {

‎templates/resources/encryption_at_rest.md.tmpl‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,9 @@ Please review the [`mongodbatlas_encryption_at_rest_private_endpoint` resource d
5353

5454

5555
### Configuring encryption at rest using customer key management in GCP
56-
For GCP environments using static service account key, we recommend configuring encryption at rest with customer key management. This approach uses role-based authentication through Cloud Provider Access for a more secure solution
56+
For GCP environments using static service account key, we recommend configuring encryption at rest with customer key management. For more details see our [Migration Guide: Encryption at Rest (GCP) Service Account JSON to Role-based Auth](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/encryption-at-rest-gcp-role-based-migration).
57+
58+
This approach uses role-based authentication through Cloud Provider Access for a more secure solution.
5759

5860
{{ tffile (printf "examples/%s/gcp/main.tf" .Name )}}
5961

0 commit comments

Comments
 (0)