Skip to content

Commit 49256ef

Browse files
lantoliCopilotmaasthamarcosuma
authored
feat: Add import support for mongodbatlas_organization resource (#3475)
* import * optional * getAtlasV2Connection * changelog * creation-only attributes * doc * examples * rename * rename * improve import example * Update internal/service/organization/resource_organization.go Co-authored-by: Copilot <[email protected]> * fix version.tf * fix example linter * Update .changelog/3475.txt Co-authored-by: maastha <[email protected]> * mention import only in its section * update example doc * improve federation_settings_id in examples * validate creation required and creation only attributes * federation_settings_id doc * simplify example main readme * update federation_settings_id in examples * revert changes to step-1 * guide * import test * SkipInUnitTest * Update docs/guides/importing-organization.md Co-authored-by: Marco Suma <[email protected]> * Update docs/guides/importing-organization.md Co-authored-by: Marco Suma <[email protected]> * Update docs/guides/importing-organization.md Co-authored-by: Marco Suma <[email protected]> * API credentials doc * PreCheckBasic, project_id is not needed * Update docs/guides/importing-organization.md Co-authored-by: Marco Suma <[email protected]> * add prevent_destroy * don't mention TF version * reference guide from resource doc * remove output from example * import block * join how and why * typo --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: maastha <[email protected]> Co-authored-by: Marco Suma <[email protected]>
1 parent e3fce7f commit 49256ef

File tree

11 files changed

+476
-100
lines changed

11 files changed

+476
-100
lines changed

‎.changelog/3475.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```release-note:enhancement
2+
resource/mongodbatlas_organization: Adds import support
3+
```

‎docs/guides/importing-organization.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
page_title: "Guide: Importing MongoDB Atlas Organizations"
3+
---
4+
5+
# Importing MongoDB Atlas Organizations
6+
7+
**Objective**: Learn how to import existing MongoDB Atlas organizations into Terraform management, understand why certain attributes are optional for imports, and successfully manage your existing organizations using Infrastructure as Code.
8+
9+
## Overview
10+
11+
Starting with version 1.38.0 of the MongoDB Atlas Provider, you can now import existing MongoDB Atlas organizations into your Terraform state. This feature allows you to bring organizations that were created outside of Terraform under Infrastructure as Code (IaC) management.
12+
13+
## Why Import Organizations?
14+
15+
Before version 1.38.0, the `mongodbatlas_organization` resource did not support the import functionality. Organizations could only be created through Terraform, which meant:
16+
17+
- Existing organizations created through the Atlas UI or API couldn't be managed by Terraform.
18+
- Teams had to maintain organizations outside of their IaC workflows.
19+
- There was no migration path to bring existing organizations under Terraform management.
20+
21+
With import support, you can now:
22+
- Bring existing organizations into Terraform management.
23+
- Standardize organization configuration across your infrastructure.
24+
- Apply consistent security settings and policies using IaC.
25+
26+
## Important Changes to Required Attributes
27+
28+
To enable import functionality, several attributes that were previously marked as required have been made optional:
29+
30+
- `org_owner_id`
31+
- `description`
32+
- `role_names`
33+
34+
This change was done because these attributes are only needed when creating a new organization and are not returned by the Atlas API when reading existing organizations so they will be empty if the resource is imported.
35+
36+
While these attributes are now optional in the schema, they are still **required when creating a new organization**. The provider will validate that these attributes are present during the creation process.
37+
38+
## How to Import an Organization
39+
40+
### Prerequisites
41+
42+
Before importing an organization, ensure you have:
43+
- MongoDB Atlas API credentials with Organization Owner permissions.
44+
- The Organization ID of the organization you want to import.
45+
- MongoDB Atlas Provider version 1.38.0 or later.
46+
47+
### Finding Your Organization ID
48+
49+
You can find your organization ID in several ways:
50+
51+
1. **Atlas UI**: Navigate to your organization settings - the ID is visible in the URL.
52+
2. **Atlas CLI**: Use `atlas organizations list` if you have the Atlas CLI installed.
53+
3. **Atlas API**: Use the organizations endpoint to list all organizations.
54+
55+
### Import Process
56+
57+
#### Step 1: Create the Terraform Configuration
58+
59+
Create a Terraform configuration file that describes the organization you want to import and the `import block`. **Do not include** the creation-only attributes:
60+
61+
```hcl
62+
resource "mongodbatlas_organization" "imported" {
63+
name = "My Existing Organization"
64+
}
65+
66+
import {
67+
id = "<ORG_ID>"
68+
to = mongodbatlas_organization.imported
69+
}
70+
71+
```
72+
73+
#### Step 2: Run the Import Command
74+
75+
Alternatively, you can use the `import command` instead of the `import block`:
76+
77+
```bash
78+
terraform import mongodbatlas_organization.imported <ORG_ID>
79+
```
80+
81+
Replace `<ORG_ID>` with your actual organization ID.
82+
83+
#### Step 3: Verify the Import
84+
85+
Run `terraform plan` to verify that the import was successful and see if any configuration adjustments are needed:
86+
87+
```bash
88+
terraform plan
89+
```
90+
91+
The plan should show minimal or no changes if your configuration matches the existing organization settings.
92+
93+
#### Step 4: Apply Any Updates
94+
95+
If you want to update any organization settings, modify your configuration and apply changs, e.g.:
96+
97+
```bash
98+
resource "mongodbatlas_organization" "imported" {
99+
name = "My Existing Organization"
100+
101+
# Add any settings that you want to modify
102+
api_access_list_required = false
103+
multi_factor_auth_required = true
104+
restrict_employee_access = true
105+
gen_ai_features_enabled = true
106+
security_contact = "[email protected]"
107+
skip_default_alerts_settings = true
108+
}
109+
```
110+
111+
## Important Considerations
112+
113+
### API Credentials Usage
114+
115+
- When importing an organization, the provider API credentials are used. Ensure that your API key has Organization Owner permissions for the organization being imported.
116+
- When creating an organization, the process remains unchanged: new API keys are generated as part of the resource creation, and these keys will be used for subsequent `mongodbatlas_organization` resource operations.
117+
118+
**Important**: API credentials stored in the `mongodbatlas_organization` Terraform state will take precedence, regardless of their validity.
119+
120+
### Creation-Only Attributes
121+
122+
The newly-declared optional attributes **cannot be specified** when importing:
123+
- `org_owner_id` - The organization owner is already set.
124+
- `description` - API key description from organization creation.
125+
- `role_names` - API key roles from organization creation.
126+
- `federation_settings_id` - Federation settings from organization creation.
127+
128+
If you include these in your configuration when importing, Terraform will show them as changes that cannot be applied.
129+
130+
### State Management
131+
132+
After a successful import:
133+
- The organization will be fully managed by Terraform.
134+
- You can update any modifiable attributes through Terraform.
135+
- The `private_key` and `public_key` attributes will be empty (as these are only generated during organization creation).
136+
137+
## Example: Complete Import Workflow
138+
139+
For a complete example of importing an organization, including all configuration files and detailed instructions, see the [organization-import example](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_organization/organization-import) in the provider repository.
140+
141+
## Troubleshooting
142+
143+
### Common Issues
144+
145+
1. **"cannot be changed after creation" errors during import**: Ensure you haven't included creation-only attributes in your configuration
146+
2. **Permission errors**: Verify your provider API key has Organization Owner role
147+
3. **Resource not found**: Double-check the organization ID is correct
148+
149+
## See Also
150+
151+
- [mongodbatlas_organization Resource Documentation](../resources/organization)
152+
- [Example: Creating a New Organization](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_organization)
153+
- [MongoDB Atlas Admin API Organization](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-organizations).

‎docs/resources/organization.md

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,11 @@
66

77
~> **IMPORTANT NOTE:** To use this resource, the requesting API Key must have the Organization Owner role. The requesting API Key's organization must be a paying organization. To learn more, see Configure a Paying Organization in the MongoDB Atlas documentation.
88

9-
~> **NOTE** Import command is currently not supported for this resource.
10-
119
## Example Usage
1210

1311
```terraform
1412
resource "mongodbatlas_organization" "test" {
15-
org_owner_id = "6205e5fffff79cde6f"
13+
org_owner_id = "<ORG_OWNER_ID>"
1614
name = "testCreateORG"
1715
description = "test API key from Org Creation Test"
1816
role_names = ["ORG_OWNER"]
@@ -21,14 +19,14 @@ resource "mongodbatlas_organization" "test" {
2119

2220
## Argument Reference
2321

24-
* `name` - (Required) The name of the organization you want to create. (Cannot be changed via this Provider after creation.)
25-
* `org_owner_id` - (Required) Unique 24-hexadecimal digit string that identifies the Atlas user that you want to assign the Organization Owner role. This user must be a member of the same organization as the calling API key. This is only required when authenticating with Programmatic API Keys. [MongoDB Atlas Admin API - Get User By Username](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/MongoDB-Cloud-Users/operation/getUserByUsername)
26-
* `description` - (Required) Programmatic API Key description
22+
* `name` - (Required) The name of the organization.
23+
* `org_owner_id` - (Optional) Unique 24-hexadecimal digit string that identifies the Atlas user that you want to assign the Organization Owner role. This user must be a member of the same organization as the calling API key. This is only required when authenticating with Programmatic API Keys. [MongoDB Atlas Admin API - Get User By Username](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/MongoDB-Cloud-Users/operation/getUserByUsername). This attribute is required in creation and can't be updated later.
24+
* `description` - (Optional) Programmatic API Key description. This attribute is required in creation and can't be updated later.
2725

28-
~> **NOTE:** Creating an organization will return a new API Key pair that can be used to authenticate and manage the new organization with MongoDB Atlas Terraform modules/blueprints. You cannot use the newly created API key pair to manage the newly created organization in the same Terraform module/blueprint that the organization is created in.
26+
~> **NOTE:** Creating an organization will return a new API Key pair that can be used to authenticate and manage the new organization with MongoDB Atlas Terraform modules/blueprints. These credentials will be used by the `mongodbatlas_organization` resource. In case of importing the resource, these credentials will be empty so the provider credentials will be used instead.
2927

30-
* `role_names` - (Required) List of Organization roles that the Programmatic API key needs to have. Ensure that you provide at least one role and ensure all roles are valid for the Organization. You must specify an array even if you are only associating a single role with the Programmatic API key. The [MongoDB Documentation](https://www.mongodb.com/docs/atlas/reference/user-roles/#organization-roles) describes the roles that you can assign to a Programmatic API key.
31-
* `federation_settings_id` - (Optional) Unique 24-hexadecimal digit string that identifies the federation to link the newly created organization to. If specified, the proposed Organization Owner of the new organization must have the Organization Owner role in an organization associated with the federation.
28+
* `role_names` - (Optional) List of Organization roles that the Programmatic API key needs to have. Ensure that you provide at least one role and ensure all roles are valid for the Organization. You must specify an array even if you are only associating a single role with the Programmatic API key. The [MongoDB Documentation](https://www.mongodb.com/docs/atlas/reference/user-roles/#organization-roles) describes the roles that you can assign to a Programmatic API key. This attribute is required in creation and can't be updated later.
29+
* `federation_settings_id` - (Optional) Unique 24-hexadecimal digit string that identifies the federation to link the newly created organization to. If specified, the proposed Organization Owner of the new organization must have the Organization Owner role in an organization associated with the federation. This attribute can't be updated after creation.
3230
* `api_access_list_required` - (Optional) Flag that indicates whether to require API operations to originate from an IP Address added to the API access list for the specified organization.
3331
* `multi_factor_auth_required` - (Optional) Flag that indicates whether to require users to set up Multi-Factor Authentication (MFA) before accessing the specified organization. To learn more, see: https://www.mongodb.com/docs/atlas/security-multi-factor-authentication/.
3432
* `restrict_employee_access` - (Optional) Flag that indicates whether to block MongoDB Support from accessing Atlas infrastructure for any deployment in the specified organization without explicit permission. Once this setting is turned on, you can grant MongoDB Support a 24-hour bypass access to the Atlas deployment to resolve support issues. To learn more, see: https://www.mongodb.com/docs/atlas/security-restrict-support-access/.
@@ -38,8 +36,6 @@ resource "mongodbatlas_organization" "test" {
3836

3937
~> **NOTE:** - If you create an organization with our Terraform provider version >=1.30.0, this field is set to `true` by default.<br> - If you have an existing organization created with our Terraform provider version <1.30.0, this field might be `false`, which is the [API default value](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createorganization). To prevent the creation of future default alerts, set this explicitly to `true`.
4038

41-
42-
4339
## Attributes Reference
4440

4541
In addition to all arguments above, the following attributes are exported:
@@ -48,5 +44,16 @@ In addition to all arguments above, the following attributes are exported:
4844
* `public_key` - Public API key value set for the specified organization API key.
4945
* `private_key` - Redacted private key returned for this organization API key. This key displays unredacted when first created and is saved within the Terraform state file.
5046

47+
## Import
48+
49+
You can import an existing organization using the organization ID, e.g.:
50+
51+
```
52+
$ terraform import mongodbatlas_organization.example 5d09d6a59ccf6445652a444a
53+
```
54+
55+
~> **IMPORTANT:** When importing an existing organization, you should **NOT** specify the creation-only attributes (`org_owner_id`, `description`, `role_names`, `federation_settings_id`) in your Terraform configuration.
56+
57+
See the [Guide: Importing MongoDB Atlas Organizations](../guides/importing-organization) for more information.
5158

52-
For more information see: [MongoDB Atlas Admin API Organization](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/#tag/Organizations/operation/createOrganization) Documentation for more information.
59+
For more information about the `mongodbatlas_organization` resource see: [MongoDB Atlas Admin API Organization](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-organizations).

‎examples/mongodbatlas_organization/Readme.md renamed to ‎examples/mongodbatlas_organization/README.md

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

2-
# Example - A basic example to create and Orgnization with MongoDB Atlas and Terraform
2+
# Example - MongoDB Atlas Organization with Terraform
33

4-
This project aims to provide a very straight-forward example of setting up a MongoDB Atlas Organization with Terraform. This will create the following resources in MongoDB Atlas:
4+
This project provides examples for both creating new MongoDB Atlas Organizations and importing existing ones using Terraform.
55

66
- MongoDB Atlas organization
77
- Private Key
@@ -13,11 +13,11 @@ This project aims to provide a very straight-forward example of setting up a Mon
1313

1414
* Terraform v0.15 or greater
1515
* A MongoDB Atlas account
16-
* provider.mongodbatlas: version = "~> 1.10.0"
16+
* provider.mongodbatlas: version = "~> 1.10.0" for creating an organization, 1.38.0 for importing an existing organization.
1717
* [Cross-organization billing](https://www.mongodb.com/docs/atlas/billing/#cross-organization-billing) enabled and the requesting API Key's organization must be a paying organization.
1818
* Some users (see [here](https://github.com/mongodb/terraform-provider-mongodbatlas/issues/1083)) have reported issues deploying this starter example with Mac M1 CPU. you encounter this issue, try deploying instead on x86 linux if possible. See list of supported binaries [here](https://github.com/mongodb/terraform-provider-mongodbatlas/releases/tag/v1.8.1)
1919

20-
## Usage
20+
## Usage - New organization
2121
**1\. change working directry to folder organization-step-1.**
2222

2323
**2\. Ensure your MongoDB Atlas credentials are set up.**
@@ -67,9 +67,9 @@ Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
6767

6868
Outputs:
6969

70-
org_id = "647ffffffe9903b4"
71-
org_private_key = "a6300e-ffffffff-8c1168f0"
72-
org_public_key = "yqffje"
70+
org_id = "<ORG_ID>"
71+
org_private_key = "<ORG_PRIVATE_KEY>"
72+
org_public_key = "<ORG_PUBLIC_KEY>"
7373

7474
**5\. Retain values for org_private_key and org_public_key for next stage of example as new API key has access to create resources in new organization.**
7575

@@ -153,3 +153,9 @@ mongodbatlas_organization.test: Destruction complete after 9s
153153

154154
Destroy complete! Resources: 1 destroyed.
155155

156+
157+
## Usage - Importing an existing organization
158+
159+
This is useful when you already have the MongoDB Atlas organization created but you want to start managing its settings with Infrastructure as Code.
160+
161+
See the example in directory [./organization-import](./organization-import).

‎examples/mongodbatlas_organization/organization-import/README.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# MongoDB Atlas Organization Import Example
2+
3+
This example demonstrates how to import an existing MongoDB Atlas organization into Terraform management.
4+
5+
## Overview
6+
7+
When you have an existing MongoDB Atlas organization that you want to manage with Terraform, you can import it using the organization ID. This is useful when you have an existing organization that was created outside of Terraform and want to start managing its settings with Infrastructure as Code.
8+
9+
Don't include `org_owner_id`, `description`, `role_names` or `federation_settings_id` when importing an organization as they are creation-only attributes.
10+
11+
## Dependencies
12+
13+
- Terraform v0.15 or greater
14+
- provider.mongodbatlas: version = "~> 1.38.0"
15+
- MongoDB Atlas account with an existing organization
16+
- API key with Organization Owner permissions for the organization you want to import
17+
- Organization ID of the existing organization
18+
19+
## Usage
20+
21+
### 1. Set up your credentials
22+
23+
Create a `terraform.tfvars` file with your Atlas credentials:
24+
25+
```hcl
26+
public_key = "<PUBLIC_KEY>"
27+
private_key = "<PRIVATE_KEY>"
28+
org_name = "<ORG_NAME>"
29+
30+
# Optional: Configure organization settings
31+
api_access_list_required = false
32+
multi_factor_auth_required = true
33+
restrict_employee_access = true
34+
gen_ai_features_enabled = true
35+
security_contact = "<SECURITY_CONTACT_EMAIL>"
36+
skip_default_alerts_settings = true
37+
```
38+
39+
### 2. Initialize Terraform
40+
41+
```bash
42+
terraform init
43+
```
44+
45+
### 3. Import the organization
46+
47+
Replace `<ORG_ID>` with your actual organization ID:
48+
49+
```bash
50+
terraform import mongodbatlas_organization.imported <ORG_ID>
51+
```
52+
53+
To find your organization ID:
54+
1. Log into MongoDB Atlas
55+
2. Go to your organization settings
56+
3. The organization ID is displayed in the URL or settings page
57+
58+
### 4. Review the plan
59+
60+
```bash
61+
terraform plan
62+
```
63+
64+
This will show you what changes (if any) Terraform will make to align your organization with the configuration.
65+
66+
### 5. Apply changes
67+
68+
```bash
69+
terraform apply
70+
```
71+
72+
## Finding Your Organization ID
73+
74+
You can find your organization ID in several ways:
75+
76+
1. **Atlas UI**: Navigate to your organization settings - the ID is visible in the URL
77+
2. **Atlas API**: Use the `organizations` endpoint to list all organizations
78+
3. **Atlas CLI**: Use `atlas organizations list` if you have the Atlas CLI installed
79+
80+
## Outputs
81+
82+
After successful import, you'll have access to:
83+
- `org_name` - The organization name
84+
85+
**Note**: Unlike when creating a new organization, importing does not provide `public_key` and `private_key` outputs since these are only generated during organization creation.

‎examples/mongodbatlas_organization/organization-import/main.tf

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Example configuration for importing an existing MongoDB Atlas organization
2+
3+
resource "mongodbatlas_organization" "imported" {
4+
name = var.org_name
5+
6+
# Optional settings - configure these to match your existing organization
7+
api_access_list_required = var.api_access_list_required
8+
multi_factor_auth_required = var.multi_factor_auth_required
9+
restrict_employee_access = var.restrict_employee_access
10+
gen_ai_features_enabled = var.gen_ai_features_enabled
11+
security_contact = var.security_contact
12+
skip_default_alerts_settings = var.skip_default_alerts_settings
13+
}

‎examples/mongodbatlas_organization/organization-import/provider.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.public_key
3+
private_key = var.private_key
4+
}

0 commit comments

Comments
 (0)