doc: Migration guide for mongodbatlas_project.teams attribute to the mongodbatlas_team_project_assignment resource (#3612)

* Migration guide

* WIP - Examples

* Outputs

* Fix

* Format

* Apply suggestions from code review

Co-authored-by: maastha <[email protected]>

* end of file

* Update examples/migrate_team_project_assignment/README.md

Co-authored-by: Evelyn Rabil <[email protected]>

* pr comments

---------

Co-authored-by: Cristina Sánchez Sánchez <[email protected]>
Co-authored-by: Oriol <[email protected]>
Co-authored-by: maastha <[email protected]>
Co-authored-by: Evelyn Rabil <[email protected]>

Author: 5 people

docs/guides/team-project-assignment-migration-guide.md

@@ -0,0 +1,160 @@
+---  
+page_title: "Migration Guide: Project Teams Attribute to Team Project Assignment Resource"
+---  
+  
+# Migration Guide: Project Teams Attribute to Team Project Assignment Resource
+  
+**Objective:** Migrate from the deprecated `teams` attribute on the `mongodbatlas_project` resource to the new `mongodbatlas_team_project_assignment` resource.  
+  
+---  
+  
+## Before you begin  
+  
+- **Backup** your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).  
+- Ensure you are using the MongoDB Atlas Terraform Provider `2.0.0` or later (version that includes `mongodbatlas_team_project_assignment` resource).
+  
+---  
+  
+## Why should I migrate?  
+  
+- **Future compatibility:** The `teams` attribute inside `mongodbatlas_project` is deprecated and will be removed in a future provider release.  
+- **Separation of concerns:** Manage projects and team-to-project role assignments independently.  
+- **Clearer diffs:** Role or team modifications won't require re‑applying the entire project resource.  
+  
+---  
+  
+## What's changing?  
+  
+- Historically, `mongodbatlas_project` accepted an inline `teams` block to assign one or more teams to a project with specific roles.  
+- Now, each project-team role mapping must be managed with `mongodbatlas_team_project_assignment`.
+
+---
+
+## From `mongodbatlas_project.teams` to `mongodbatlas_team_project_assignment`
+
+### Original configuration
+  
+```hcl  
+locals {  
+  project_id = <PROJECT_ID>  
+  team_map = { # team_id => set(role_names)
+    <TEAM_ID_1>  = ["GROUP_OWNER"]
+    <TEAM_ID_2>  = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_WRITE"]
+  }
+}
+
+resource "mongodbatlas_project" "this" {
+  name             = "<PROJECT_NAME>"
+  org_id           = "<ORG_ID>"
+  project_owner_id = "<OWNER_ID>"
+
+  dynamic "teams" {
+    for_each = local.team_map
+    content {  
+      team_id    = teams.key  
+      role_names = teams.value  
+    }  
+  }  
+}  
+```  
+
+---  
+  
+### Step 1: Ignore `teams` and remove from configuration
+
+-> **Note:** The `teams` attribute is a `SetNestedBlock` and cannot be marked `Optional`/`Computed` for a smooth migration. For now, `ignore_changes` is required during Step 1. Support for removing `teams` entirely will come in a future Atlas Provider release.
+
+Replace the `mongodbatlas_project.teams` block with:  
+  
+```hcl  
+resource "mongodbatlas_project" "this" {  
+  name             = "<PROJECT_NAME>"
+  org_id           = "<ORG_ID>"
+  project_owner_id = "<OWNER_ID>"  
+  
+  lifecycle {  
+    ignore_changes = ["teams"]  
+  }  
+}  
+```  
+  
+Then run:  
+  
+```shell  
+terraform plan  
+terraform apply  
+```  
+  
+This removes the `teams` block from the config but keeps the assignments in Atlas unchanged until we explicitly manage them in new resources.  
+  
+---  
+  
+### Step 2: Add the new `mongodbatlas_team_project_assignment` resources  
+  
+```hcl  
+resource "mongodbatlas_project" "this" {  
+  name             = "<PROJECT_NAME>"
+  org_id           = "<ORG_ID>"
+  project_owner_id = "<OWNER_ID>"  
+  
+  lifecycle {  
+    ignore_changes = ["teams"]  
+  }  
+}
+
+resource "mongodbatlas_team_project_assignment" "this" {  
+  for_each = local.team_map  
+  
+  project_id = mongodbatlas_project.this.id  
+  team_id    = each.key  
+  role_names = each.value  
+}  
+ 
+import {  
+  for_each = local.team_map
+
+  to       = mongodbatlas_team_project_assignment.this[each.key]
+  id       = "${mongodbatlas_project.this.id}/${each.key}"
+}  
+```
+  
+Run `terraform plan` (you should see **import** operations), then `terraform apply`. 
+  
+---  
+  
+### Step 4: Verify and clean up  
+  
+- After successful import and apply, `terraform plan` should show **no changes**.  
+- Keep the `ignore_changes = ["teams"]` lifecycle rule until the provider releases a version without the `teams` argument in `mongodbatlas_project`.  
+  
+---
+
+## Examples
+
+For complete, working configurations that demonstrate the migration process, see the examples in the provider repository: [migrate_team_project_assignment](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_team_project_assignment).
+
+The examples include:
+- **v1**: Original configuration using deprecated `teams` attribute in `mongodbatlas_project` resource.
+- **v2**: Final configuration using `mongodbatlas_team_project_assignment` resource for team-to-project assignments.
+  
+## Notes and tips  
+  
+- **Import format** for `mongodbatlas_team_project_assignment`:  
+```  
+PROJECT_ID/TEAM_ID  
+```  
+- **Modules:** Terraform import blocks cannot live inside modules ([Terraform issue](https://github.com/hashicorp/terraform/issues/33474)). 
+- If you manage team assignments in modules, import each at the root level using the correct resource address (e.g. `module.<name>.mongodbatlas_team_project_assignment.<name>`).  
+- You can use `terraform plan` to confirm imports before applying.  
+  
+---  
+  
+## FAQ  
+
+**Q: Do I need to delete the old `teams` from state?**
+A: No — using `ignore_changes` ensures they remain in Atlas until the provider removes the field. Then you can drop the lifecycle rule.  
+  
+---  
+  
+## Further resources  
+- [`mongodbatlas_team_project_assignment` docs](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/team_project_assignment)

examples/migrate_team_project_assignment/README.md

@@ -0,0 +1,40 @@
+# Migration Example: Team Project Attribute to Team Project Assignment
+
+This example demonstrates how to migrate from the deprecated `mongodbatlas_project.teams` attribute to the new `mongodbatlas_team_project_assignment` resource.
+
+## Migration Phases
+
+### v1: Initial State (Deprecated Resource)
+Shows the original configuration using deprecated `mongodbatlas_project.teams` attribute for team assignments.
+
+### v2: Final State (New Resource Only)
+Update the configuration to use `mongodbatlas_team_project_assignment` and migrate away from deprecated `mongodbatlas_project.teams`.
+
+## Usage
+
+1. Start with v1 to understand the original setup with team assignments
+2. Apply v2 configuration to import existing assignments with new resource and no longer use deprecated attribute teams
+
+## Prerequisites
+
+- MongoDB Atlas Terraform Provider 2.0.0 or later
+- Valid MongoDB Atlas and Team IDs
+
+## Variables
+
+Set these variables for all versions:
+
+```terraform
+public_key   = <ATLAS_PUBLIC_KEY>  # Optional, can use env vars
+private_key  = <ATLAS_PRIVATE_KEY> # Optional, can use env vars
+team_id_1    = <TEAM_ID_1>         # Team to assign
+team_id_2    = <TEAM_ID_2>         # Another team to assign
+team_1_roles = ["GROUP_OWNER"]
+team_2_roles = ["GROUP_READ_ONLY", "GROUP_DATA_ACCESS_READ_WRITE"]
+```
+
+Alternatively, set environment variables:
+```bash
+export MONGODB_ATLAS_PUBLIC_KEY="your-public-key"
+export MONGODB_ATLAS_PRIVATE_KEY="your-private-key"
+```

examples/migrate_team_project_assignment/v1/main.tf

@@ -0,0 +1,38 @@
+############################################################
+# v1: Original configuration using deprecated attribute
+############################################################
+
+# Map of team IDs to their roles
+locals {
+  team_map = {
+    (var.team_id_1) = var.team_1_roles
+    (var.team_id_2) = var.team_2_roles
+  }
+}
+
+# Using deprecated team block inside mongodbatlas_project to assign teams to the project
+resource "mongodbatlas_project" "this" {
+  name   = "this"
+  org_id = var.org_id
+
+  dynamic "teams" {
+    for_each = local.team_map
+    content {
+      team_id    = teams.key
+      role_names = teams.value
+    }
+  }
+}
+
+output "project_teams" {
+  description = "List of teams assigned to the Atlas project, with their roles"
+  value       = mongodbatlas_project.this.teams
+}
+
+output "project_teams_map" {
+  description = "Map of team IDs to their roles (from teams attribute)"
+  value = {
+    for t in mongodbatlas_project.this.teams :
+    t.team_id => t.role_names
+  }
+}

examples/migrate_team_project_assignment/v1/provider.tf

@@ -0,0 +1,4 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}

examples/migrate_team_project_assignment/v1/variables.tf

@@ -0,0 +1,35 @@
+variable "org_id" {
+  description = "The ID of the MongoDB Atlas organization"
+  type        = string
+}
+
+variable "team_id_1" {
+  description = "The ID of the first team"
+  type        = string
+}
+
+variable "team_1_roles" {
+  description = "Roles to assign to the first team in the project"
+  type        = list(string)
+}
+
+variable "team_id_2" {
+  description = "The ID of the second team"
+  type        = string
+}
+
+variable "team_2_roles" {
+  description = "Roles to assign to the second team in the project"
+  type        = list(string)
+}
+
+variable "public_key" {
+  description = "Public key for MongoDB Atlas API"
+  type        = string
+  default     = ""
+}
+variable "private_key" {
+  description = "Private key for MongoDB Atlas API"
+  type        = string
+  default     = ""
+}

examples/migrate_team_project_assignment/v1/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.7.0"
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.0" // TODO: CLOUDP-335982: Update to 2.0.0
+    }
+  }
+}

examples/migrate_team_project_assignment/v2/README.md

@@ -0,0 +1,24 @@
+# v2: Final State
+
+This is the final configuration using only the new `mongodbatlas_team_project_assignment` resource while ignoring the deprecated `mongodbatlas_project.teams` attribute.
+
+## What changed from v1
+
+### Resource purpose
+- **Old**: Managed through deprecated `mongodbatlas_project.teams` attribute
+- **New**: Uses `mongodbatlas_team_project_assignment` resource for team-to-project assignments
+
+### Data source support
+- **Old**: Had data source for reading teams attribute
+- **New**: Has data source for reading team assignments
+
+## Usage patterns
+
+This configuration demonstrates:
+- Basic team assignment to project
+- Data source usage for reading assignments
+- Output examples showing how to print team assignments in various formats
+
+## Migration complete
+
+At this point, you have successfully migrated from the deprecated `mongodbatlas_project.teams` attribute to the new `mongodbatlas_team_project_assignment` resource. All references to the old attribute have been replaced with the new resource.

examples/migrate_team_project_assignment/v2/main.tf

@@ -0,0 +1,71 @@
+############################################################
+# v2: New resource usage
+############################################################
+
+# Map of team IDs to their roles
+locals {
+  team_map = {
+    (var.team_id_1) = var.team_1_roles
+    (var.team_id_2) = var.team_2_roles
+  }
+}
+
+# Ignore the deprecated teams block in mongodbatlas_project
+resource "mongodbatlas_project" "this" {
+  name   = "this"
+  org_id = var.org_id
+  lifecycle {
+    ignore_changes = [teams]
+  }
+}
+
+# Use the new mongodbatlas_team_project_assignment resource
+resource "mongodbatlas_team_project_assignment" "this" {
+  for_each = local.team_map
+
+  project_id = mongodbatlas_project.this.id
+  team_id    = each.key
+  role_names = each.value
+}
+
+# Import existing team-project relationships into the new resource
+import {
+  for_each = local.team_map
+  to       = mongodbatlas_team_project_assignment.this[each.key]
+  id       = "${mongodbatlas_project.this.id}/${each.key}"
+}
+
+# Example outputs showing team assignments in various formats
+output "team_project_assignments" {
+  description = "List of all team assignments for the MongoDB Atlas project"
+  value = [
+    for assignment in mongodbatlas_team_project_assignment.this :
+    {
+      team_id    = assignment.team_id
+      role_names = assignment.role_names
+    }
+  ]
+}
+
+output "team_project_assignments_map" {
+  description = "Map of team_id to role_names for the MongoDB Atlas project"
+  value = {
+    for k, assignment in mongodbatlas_team_project_assignment.this :
+    assignment.team_id => assignment.role_names
+  }
+}
+
+# Data source to read current team assignments for the project
+data "mongodbatlas_team_project_assignment" "this" {
+  project_id = mongodbatlas_project.this.id
+  team_id    = var.team_id_1 # Example for one team; repeat for others as needed
+}
+
+output "data_team_project_assignment" {
+  description = "Data source output for team assignment"
+  value = {
+    team_id    = data.mongodbatlas_team_project_assignment.this.team_id
+    project_id = data.mongodbatlas_team_project_assignment.this.project_id
+    role_names = data.mongodbatlas_team_project_assignment.this.role_names
+  }
+}

examples/migrate_team_project_assignment/v2/provider.tf

@@ -0,0 +1,4 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}