doc: Migration guide for `mongodbatlas_team.usernames` attribute to the `mongodbatlas_cloud_user_team_assignment` resource #3588

csanx · 2025-08-14T09:25:30Z

Description

Migration guide for mongodbatlas_team.usernames attribute to the mongodbatlas_cloud_user_team_assignment resource

Link to any related issue(s): CLOUDP-336760

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

Tested the migration paths successfully.

github-actions · 2025-08-14T09:48:20Z

APIx bot: a message has been sent to Docs Slack channel

csanx · 2025-08-14T09:48:46Z

@marcosuma I’m not sure we need an example created specifically for this migration, since we’re not doing anything different to support modules. Do you think it’s worth adding one?

Copilot

Pull Request Overview

This PR adds a comprehensive migration guide to help users transition from the deprecated usernames attribute on the mongodbatlas_team resource to the new mongodbatlas_cloud_user_team_assignment resource.

Key changes:

Added detailed migration documentation with step-by-step instructions
Provided practical Terraform code examples for each migration step
Included guidance on handling imports and module considerations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-14T09:49:11Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+
+---  
+
+### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs


Typo in heading: 'User' should be 'Use'.

Suggested change

### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs

### Step 1: Use `mongodb_atlas_team` data source to retrieve user IDs

Copilot · 2025-08-14T09:49:12Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+}
+
+# New resource for each (user, team) assignment  
+ resource "mongodbatlas_cloud_user_team_assignment" "this" {           


Extra space before 'resource' keyword. Should be aligned with other resource blocks.

Suggested change

resource "mongodbatlas_cloud_user_team_assignment" "this" {

resource "mongodbatlas_cloud_user_team_assignment" "this" {

marcosuma

@csanx I would still add an example for modules so it'll be crystal clear to customers what root-level import blocks means.

marcosuma · 2025-08-14T09:53:06Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+
+Handling migration in modules
+
+- Terraform import blocks cannot live inside modules; they must be defined in the root module. See ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)).


Suggested change

- Terraform import blocks cannot live inside modules; they must be defined in the root module. See ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)).

- Terraform import blocks cannot live inside modules; See ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)).

found this sentence duplicating the one just after

corryroot

LGTM

maastha · 2025-08-19T19:11:45Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+
+- `mongodbatlas_team` included a `usernames` argument that allowed assigning users to a team directly inside the resource. This argument is now deprecated.
+- New attribute `users` in `mongodbatlas_team` data source can be used to retrieve information about all the users assigned to that team.
+- `mongodbatlas_cloud_user_team_assignment` manages the user’s organization membership (pending or active) and exposes both `username` and `user_id`. It supports import using either `ORG_ID/TEAM_ID/USERNAME` or `ORG_ID/TEAM_ID/USER_ID`.


should this be "manages the user’s team membership ....."?

Yes! Changed it

maastha · 2025-08-19T19:12:13Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+
+- `mongodbatlas_team` included a `usernames` argument that allowed assigning users to a team directly inside the resource. This argument is now deprecated.
+- New attribute `users` in `mongodbatlas_team` data source can be used to retrieve information about all the users assigned to that team.
+- `mongodbatlas_cloud_user_team_assignment` manages the user’s organization membership (pending or active) and exposes both `username` and `user_id`. It supports import using either `ORG_ID/TEAM_ID/USERNAME` or `ORG_ID/TEAM_ID/USER_ID`.


[q] is there any difference between pending vs active behavior?

There shouldn't be. I've just tried it and it imports both, pending and active users. You can also add a pending user to a team.

maastha · 2025-08-19T19:14:56Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+
+---  
+
+### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs


Suggested change

### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs

### Step 1: Use `mongodbatlas_team` data source to retrieve user IDs

AgustinBettati · 2025-08-20T07:50:45Z

docs/guides/cloud_user_team_assignment_migration_guide.md

+resource "mongodbatlas_team" "this" {  
+  org_id = var.org_id  
+  name   = "this"  
+  # usernames = local.usernames  # Remove this line


I see usernames is not present in configs of step 1 and 2. We should add them there right?

You're right. Included them.

examples/migrate_user_team_assignment/README.md

oarbusi

LGTM

docs/guides/cloud_user_team_assignment_migration_guide.md

examples/migrate_user_team_assignment/module_maintainer/v1/README.md

…DME.md Co-authored-by: maastha <[email protected]>

oarbusi · 2025-08-22T13:36:32Z

merging as @csanx addressed all the comments

Cristina Sánchez Sánchez added 3 commits August 13, 2025 12:55

WIP - Migration guide

ef507c2

Migration guide

fe3b782

Changes

e5e0085

csanx changed the title ~~Migration guide for mongodbatlas_team.usernames attribute to the mongodbatlas_cloud_user_team_assignment resource~~ doc: Migration guide for mongodbatlas_team.usernames attribute to the mongodbatlas_cloud_user_team_assignment resource Aug 14, 2025

Changes

aba7bf0

csanx requested a review from a team August 14, 2025 09:44

csanx marked this pull request as ready for review August 14, 2025 09:48

Copilot AI review requested due to automatic review settings August 14, 2025 09:48

csanx requested a review from a team as a code owner August 14, 2025 09:48

Copilot AI reviewed Aug 14, 2025

View reviewed changes

marcosuma approved these changes Aug 14, 2025

View reviewed changes

marcosuma reviewed Aug 14, 2025

View reviewed changes

corryroot approved these changes Aug 14, 2025

View reviewed changes

WIP - Examples

92f23ba

maastha reviewed Aug 19, 2025

View reviewed changes

WIP - Examples

61d2d5a

AgustinBettati approved these changes Aug 20, 2025

View reviewed changes

oarbusi reviewed Aug 21, 2025

View reviewed changes

examples/migrate_user_team_assignment/README.md Outdated Show resolved Hide resolved

Cristina Sánchez Sánchez added 5 commits August 21, 2025 10:45

Migration guide examples

8f8d4e4

Changed examples directories

15de6ef

Formatting

9193ffd

Typo

9039e64

Added API Keys

766fb09

oarbusi approved these changes Aug 22, 2025

View reviewed changes

EspenAlbert reviewed Aug 22, 2025

View reviewed changes

docs/guides/cloud_user_team_assignment_migration_guide.md Show resolved Hide resolved

maastha reviewed Aug 22, 2025

View reviewed changes

examples/migrate_user_team_assignment/module_maintainer/v1/README.md Outdated Show resolved Hide resolved

oarbusi and others added 2 commits August 22, 2025 15:19

Update examples/migrate_user_team_assignment/module_maintainer/v1/REA…

238bff8

…DME.md Co-authored-by: maastha <[email protected]>

end of file

9652251

oarbusi merged commit 1096236 into CLOUDP-320243-dev-2.0.0 Aug 22, 2025
42 checks passed

oarbusi deleted the CLOUDP-336760 branch August 22, 2025 13:36


		---

		### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs

	### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs
	### Step 1: Use `mongodb_atlas_team` data source to retrieve user IDs

	resource "mongodbatlas_cloud_user_team_assignment" "this" {
	resource "mongodbatlas_cloud_user_team_assignment" "this" {


		Handling migration in modules

		- Terraform import blocks cannot live inside modules; they must be defined in the root module. See ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)).

	### Step 1: User `mongodb_atlas_team` data source to retrieve user IDs
	### Step 1: Use `mongodbatlas_team` data source to retrieve user IDs

doc: Migration guide for mongodbatlas_team.usernames attribute to the mongodbatlas_cloud_user_team_assignment resource #3588

doc: Migration guide for mongodbatlas_team.usernames attribute to the mongodbatlas_cloud_user_team_assignment resource #3588

Uh oh!

Conversation

csanx commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

Uh oh!

github-actions bot commented Aug 14, 2025

Uh oh!

csanx commented Aug 14, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

marcosuma left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

corryroot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

oarbusi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

oarbusi commented Aug 22, 2025

Uh oh!

Uh oh!

Uh oh!

doc: Migration guide for `mongodbatlas_team.usernames` attribute to the `mongodbatlas_cloud_user_team_assignment` resource #3588

doc: Migration guide for `mongodbatlas_team.usernames` attribute to the `mongodbatlas_cloud_user_team_assignment` resource #3588

csanx commented Aug 14, 2025 •

edited

Loading