Skip to content

Commit 3460629

Browse files
oarbusimarcabreracast
oarbusi
and
marcabreracast
authored
doc: Adds example for GCP in mongodbatlas_cloud_provider_access resources and mongodbatlas_encryption_at_rest resource (#3645)
* example * required_version * example for ear * make cloud provider access example focused * fixes * mention need to delete the old * update docs * Address PR comments for documentation improvements * Address PR comments * Add missing dot por documentation * Address docs generated modifications from PR comments --------- Co-authored-by: Mar Cabrera <[email protected]>
1 parent f4928d9 commit 3460629

File tree

15 files changed

+426
-15
lines changed

15 files changed

+426
-15
lines changed

‎docs/resources/encryption_at_rest.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,20 +134,37 @@ 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 authentication, you must provide either serviceAccountKey (static credentials) or roleId (service-account–based authentication). Once roleId is configured, serviceAccountKey is no longer supported.
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
138138

139139
```terraform
140+
resource "mongodbatlas_cloud_provider_access_setup" "this" {
141+
project_id = var.atlas_project_id
142+
provider_name = "GCP"
143+
}
144+
145+
resource "mongodbatlas_cloud_provider_access_authorization" "this" {
146+
project_id = var.atlas_project_id
147+
role_id = mongodbatlas_cloud_provider_access_setup.this.role_id
148+
}
149+
140150
resource "mongodbatlas_encryption_at_rest" "test" {
141151
project_id = var.atlas_project_id
142152
143153
google_cloud_kms_config {
144154
enabled = true
145-
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\"}"
146-
key_version_resource_id = "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1"
155+
key_version_resource_id = google_kms_crypto_key.crypto_key.primary[0].name
156+
role_id = mongodbatlas_cloud_provider_access_authorization.this.role_id
147157
}
158+
159+
depends_on = [
160+
google_kms_crypto_key_iam_binding.encrypter_decrypter_binding,
161+
google_kms_crypto_key_iam_binding.viewer_binding
162+
]
148163
}
149164
```
150165

166+
For a complete example that includes GCP KMS resource creation and IAM binding setup, see the [GCP encryption at rest example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest/gcp/).
167+
151168
<!-- schema generated by tfplugindocs -->
152169
## Schema
153170

‎examples/mongodbatlas_cloud_provider_access/gcp/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# MongoDB Atlas Cloud Provider Access with Google Cloud Platform (GCP)
2+
3+
This example demonstrates how to set up MongoDB Atlas Cloud Provider Access with Google Cloud Platform (GCP). This creates the necessary setup and authorization for MongoDB Atlas to access GCP resources on behalf of your project.
4+
5+
## What This Example Does
6+
7+
The following Terraform configurations:
8+
9+
1. **Creates Cloud Provider Access Setup**: Establishes the initial setup for MongoDB Atlas to access GCP resources
10+
2. **Authorizes the Access Role**: Completes the authorization process, creating a GCP service account that MongoDB Atlas can use
11+
12+
## Architecture Overview
13+
14+
```mermaid
15+
graph LR
16+
subgraph "MongoDB Atlas"
17+
A[Project<br/>Cloud Provider<br/>Access]
18+
end
19+
20+
subgraph "Google Cloud"
21+
B[Service Account<br/>Created by Atlas]
22+
end
23+
A <--> B
24+
```
25+
26+
## Prerequisites
27+
28+
Before running this example, you need:
29+
30+
1. **MongoDB Atlas Account**: With API keys that have project owner permissions
31+
2. **Google Cloud Platform Account**: With a project (no specific GCP permissions required for this setup)
32+
3. **Terraform**: Version 0.13 or later
33+
34+
## Procedure
35+
36+
### 1. Set Up Variables
37+
38+
Create a `terraform.tfvars` file:
39+
40+
```hcl
41+
atlas_public_key = "<ATLAS_PUBLIC_KEY>"
42+
atlas_private_key = "<ATLAS_PRIVATE_KEY>"
43+
atlas_project_id = "<ATLAS_PROJECT_ID>"
44+
```
45+
46+
### 2. Deploy the Infrastructure
47+
48+
```bash
49+
terraform init
50+
terraform plan
51+
terraform apply
52+
```
53+
54+
### 3. Verify the Setup
55+
56+
After having successfully deployed your infrastructure, you should get the following outputs:
57+
- Atlas role ID
58+
- GCP service account email created by Atlas
59+
60+
## Important Notes
61+
62+
### GCP-Specific Behavior
63+
64+
Unlike AWS and Azure, GCP Cloud Provider Access:
65+
- **No Configuration Updates**: GCP authorization only requires a role ID and has no additional configuration parameters
66+
- **Immutable After Creation**: Once authorized, you cannot "update" a GCP cloud provider access role
67+
- **New Authorization = New Resource**: If you need to change GCP settings, create a new `mongodbatlas_cloud_provider_access_setup` and `mongodbatlas_cloud_provider_access_authorization` resource and then delete the old one
68+
69+
### Next Steps
70+
71+
After setting up cloud provider access, you can use the created service account for various integrations such as Encryption at Rest using Google Cloud KMS. See the full example [here](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_encryption_at_rest/gcp)
72+
73+
## Variables
74+
75+
| Variable | Description | Type | Required |
76+
|----------|-------------|------|----------|
77+
| `atlas_public_key` | MongoDB Atlas public API key | string | Yes |
78+
| `atlas_private_key` | MongoDB Atlas private API key | string | Yes |
79+
| `atlas_project_id` | MongoDB Atlas project ID | string | Yes |
80+
81+
## Outputs
82+
83+
| Output | Description |
84+
|--------|-------------|
85+
| `atlas_role_id` | The MongoDB Atlas cloud provider access role ID |
86+
| `gcp_service_account_email` | GCP service account email created by Atlas |
87+
88+
## Related Documentation
89+
90+
- [MongoDB Atlas Cloud Provider Access](https://www.mongodb.com/docs/atlas/security/customer-key-management/)
91+
- [Terraform MongoDB Atlas Provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs)
92+
- [mongodbatlas_cloud_provider_access_setup](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cloud_provider_access)
93+
- [mongodbatlas_cloud_provider_access_authorization](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cloud_provider_access)

‎examples/mongodbatlas_cloud_provider_access/gcp/main.tf‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
resource "mongodbatlas_cloud_provider_access_setup" "this" {
2+
project_id = var.atlas_project_id
3+
provider_name = "GCP"
4+
}
5+
6+
resource "mongodbatlas_cloud_provider_access_authorization" "this" {
7+
project_id = var.atlas_project_id
8+
role_id = mongodbatlas_cloud_provider_access_setup.this.role_id
9+
}
10+

‎examples/mongodbatlas_cloud_provider_access/gcp/outputs.tf‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
output "atlas_role_id" {
2+
description = "The MongoDB Atlas cloud provider access role ID"
3+
value = mongodbatlas_cloud_provider_access_authorization.this.role_id
4+
}
5+
6+
output "gcp_service_account_email" {
7+
description = "The GCP service account email created by MongoDB Atlas"
8+
value = mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas
9+
}

‎examples/mongodbatlas_cloud_provider_access/gcp/providers.tf‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
provider "mongodbatlas" {
2+
public_key = var.atlas_public_key
3+
private_key = var.atlas_private_key
4+
}

‎examples/mongodbatlas_cloud_provider_access/gcp/variables.tf‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
variable "atlas_public_key" {
2+
description = "MongoDB Atlas public API key for authentication"
3+
type = string
4+
}
5+
6+
variable "atlas_private_key" {
7+
description = "MongoDB Atlas private API key for authentication"
8+
type = string
9+
sensitive = true
10+
}
11+
12+
variable "atlas_project_id" {
13+
description = "MongoDB Atlas project ID where the cloud provider access will be configured"
14+
type = string
15+
}

‎examples/mongodbatlas_cloud_provider_access/gcp/versions.tf‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
terraform {
2+
required_providers {
3+
mongodbatlas = {
4+
source = "mongodb/mongodbatlas"
5+
}
6+
}
7+
required_version = ">= 0.13"
8+
}

‎examples/mongodbatlas_encryption_at_rest/gcp/README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# MongoDB Atlas Cloud Provider Access with Google Cloud Platform (GCP)
2+
3+
This example demonstrates how to set up MongoDB Atlas Cloud Provider Access with Google Cloud Platform (GCP) to enable Customer-Managed Encryption Keys (CMEK) using Google Cloud KMS.
4+
5+
## What This Example Does
6+
7+
The following Terraform configurations:
8+
9+
1. **Creates Cloud Provider Access Setup**: Establishes the initial setup for MongoDB Atlas to access GCP resources
10+
2. **Authorizes the Access Role**: Completes the authorization process, creating a GCP service account that MongoDB Atlas can use
11+
3. **Creates GCP KMS Resources**: Sets up a Key Ring and Crypto Key in Google Cloud KMS for encryption
12+
4. **Configures IAM Permissions**: Grants the MongoDB Atlas service account the necessary permissions to use the KMS key
13+
5. **Enables Encryption at Rest**: Configures MongoDB Atlas to use the GCP KMS key for encrypting data at rest
14+
15+
## Architecture Overview
16+
17+
```
18+
┌─────────────────────┐ ┌─────────────────────────┐
19+
│ MongoDB Atlas │ │ Google Cloud │
20+
│ │ │ │
21+
│ ┌───────────────┐ │ │ ┌─────────────────┐ │
22+
│ │ Project │ │ │ │ KMS Key Ring │ │
23+
│ │ │ │◄───┤ │ │ │
24+
│ │ Cloud Provider│ │ │ │ ┌─────────────┐ │ │
25+
│ │ Access │ │ │ │ │ Crypto Key │ │ │
26+
│ │ │ │ │ │ └─────────────┘ │ │
27+
│ └───────────────┘ │ │ └─────────────────┘ │
28+
│ │ │ │
29+
│ Service Account ───┼────┤► IAM Permissions │
30+
│ (Created by Atlas) │ │ - cryptoKeyEncrypter │
31+
│ │ │ Decrypter │
32+
│ │ │ - viewer │
33+
└─────────────────────┘ └─────────────────────────┘
34+
```
35+
36+
## Prerequisites
37+
38+
Before running this example, you need:
39+
40+
1. **MongoDB Atlas Account**: With API keys that have project owner permissions
41+
2. **Google Cloud Platform Account**: With a project and appropriate permissions to:
42+
- Create KMS resources (Key Rings and Crypto Keys)
43+
- Manage IAM bindings on KMS resources
44+
3. **Terraform**: Version 0.13 or later
45+
4. **Google Cloud Terraform Provider**: The Google provider must be configured in your Terraform environment. See the [Google provider documentation](https://registry.terraform.io/providers/hashicorp/google/latest/docs) for authentication methods
46+
47+
### Required GCP Permissions
48+
49+
Your user or service account needs the following IAM roles:
50+
- `roles/cloudkms.admin` - To create and manage KMS resources
51+
- `roles/resourcemanager.projectIamAdmin` - To manage IAM bindings
52+
53+
## Procedure
54+
55+
### 1. Set Up Variables
56+
57+
Create a `terraform.tfvars` file:
58+
59+
```hcl
60+
atlas_public_key = <ATLAS_PUBLIC_KEY>
61+
atlas_private_key = <ATLAS_PRIVATE_KEY>
62+
atlas_project_id = <ATLAS_PROJECT_ID>
63+
gcp_project_id = <GCP_PROJECT_ID>
64+
65+
# Optional: Customize KMS resources
66+
key_ring_name = <KEY_RING_NAME>
67+
crypto_key_name = <CRYPTO_KEY_NAME>
68+
location = <GCP_LOCATION>
69+
```
70+
71+
### 2. Deploy the Infrastructure
72+
73+
```bash
74+
terraform init
75+
terraform plan
76+
terraform apply
77+
```
78+
79+
### 3. Verify the Setup
80+
81+
After having successfully deployed your infrastructure, you should get the following outputs:
82+
- Atlas role ID
83+
- GCP service account email created by Atlas
84+
- KMS key ring and crypto key IDs
85+
- Key version resource ID used for encryption
86+
87+
### Resource Dependencies
88+
89+
The configuration manages dependencies between resources:
90+
- KMS resources are created first
91+
- Atlas authorization completes before encryption configuration
92+
- IAM bindings are established before Atlas tries to use the key
93+
94+
### Security Considerations
95+
96+
- The Atlas service account gets minimal required permissions (`cryptoKeyEncrypterDecrypter` and `viewer`)
97+
- KMS keys are created with `ENCRYPT_DECRYPT` purpose only
98+
99+
## Variables
100+
101+
| Variable | Description | Type | Default | Required |
102+
|----------|-------------|------|---------|----------|
103+
| `atlas_public_key` | MongoDB Atlas public API key | string | - | Yes |
104+
| `atlas_private_key` | MongoDB Atlas private API key | string | - | Yes |
105+
| `atlas_project_id` | MongoDB Atlas project ID | string | - | Yes |
106+
| `gcp_project_id` | GCP project ID | string | - | Yes |
107+
| `key_ring_name` | Name of the KMS key ring | string | `"atlas-key-ring"` | No |
108+
| `crypto_key_name` | Name of the crypto key | string | `"atlas-crypto-key"` | No |
109+
| `location` | GCP region for KMS resources | string | `"us-central1"` | No |
110+
111+
## Outputs
112+
113+
| Output | Description |
114+
|--------|-------------|
115+
| `atlas_role_id` | The MongoDB Atlas cloud provider access role ID |
116+
| `gcp_service_account_email` | GCP service account email created by Atlas |
117+
| `kms_key_ring_id` | Full ID of the created KMS key ring |
118+
| `kms_crypto_key_id` | Full ID of the created crypto key |
119+
| `kms_key_version_resource_id` | Resource ID of the primary key version |
120+
121+
## Related Documentation
122+
123+
- [MongoDB Atlas Cloud Provider Access](https://www.mongodb.com/docs/atlas/security/customer-key-management/)
124+
- [Google Cloud KMS Documentation](https://cloud.google.com/kms/docs)
125+
- [Terraform MongoDB Atlas Provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs)

‎examples/mongodbatlas_encryption_at_rest/gcp/gcp-kms.tf‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Create the Key Ring
2+
resource "google_kms_key_ring" "key_ring" {
3+
name = var.key_ring_name
4+
location = var.location
5+
}
6+
7+
# Create the Crypto Key in the Key Ring
8+
resource "google_kms_crypto_key" "crypto_key" {
9+
name = var.crypto_key_name
10+
key_ring = google_kms_key_ring.key_ring.id
11+
purpose = "ENCRYPT_DECRYPT"
12+
}
13+
14+
# IAM Binding: Grant 'cryptoKeyEncrypterDecrypter' role
15+
resource "google_kms_crypto_key_iam_binding" "encrypter_decrypter_binding" {
16+
crypto_key_id = google_kms_crypto_key.crypto_key.id
17+
role = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
18+
19+
members = [
20+
"serviceAccount:${mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas}"
21+
]
22+
}
23+
24+
# IAM Binding: Grant 'viewer' role
25+
resource "google_kms_crypto_key_iam_binding" "viewer_binding" {
26+
crypto_key_id = google_kms_crypto_key.crypto_key.id
27+
role = "roles/cloudkms.viewer"
28+
29+
members = [
30+
"serviceAccount:${mongodbatlas_cloud_provider_access_authorization.this.gcp[0].service_account_for_atlas}"
31+
]
32+
}

‎examples/mongodbatlas_encryption_at_rest/gcp/main.tf‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
resource "mongodbatlas_cloud_provider_access_setup" "this" {
2+
project_id = var.atlas_project_id
3+
provider_name = "GCP"
4+
}
5+
6+
resource "mongodbatlas_cloud_provider_access_authorization" "this" {
7+
project_id = var.atlas_project_id
8+
role_id = mongodbatlas_cloud_provider_access_setup.this.role_id
9+
}
10+
11+
resource "mongodbatlas_encryption_at_rest" "test" {
12+
project_id = var.atlas_project_id
13+
14+
google_cloud_kms_config {
15+
enabled = true
16+
key_version_resource_id = google_kms_crypto_key.crypto_key.primary[0].name
17+
role_id = mongodbatlas_cloud_provider_access_authorization.this.role_id
18+
}
19+
20+
depends_on = [
21+
google_kms_crypto_key_iam_binding.encrypter_decrypter_binding,
22+
google_kms_crypto_key_iam_binding.viewer_binding
23+
]
24+
}

0 commit comments

Comments
 (0)