doc: Example for migration of mongodbatlas_org_invitation resource and data source to the mongodbatlas_cloud_user_org_assignment resource (#3589)

* examples

* Update examples/migrate_org_invitation_to_cloud_user_org_assignment/v2/README.md

* Update examples/migrate_org_invitation_to_cloud_user_org_assignment/v2/README.md

Co-authored-by: Marco Suma <[email protected]>

* pr comments

* fix from resource

* reference example in migration guide

---------

Co-authored-by: Marco Suma <[email protected]>

Author: oarbusi

docs/guides/org-invitation-to-cloud-user-org-assignment-migration-guide.md

@@ -224,6 +224,12 @@ Then:
 
 ---
 
+## Examples
+
+For complete, working configurations that mirror the use-cases above, see the examples in the provider repository: [migrate_org_invitation_to_cloud_user_org_assignment](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/v2.0.0/examples/migrate_org_invitation_to_cloud_user_org_assignment). These include root-level setups for multiple approaches (e.g., moved blocks and imports) across different versions.
+
+---
+
 ## Notes and tips
 
 - Import formats:

examples/migrate_org_invitation_to_cloud_user_org_assignment/README.md

@@ -0,0 +1,16 @@
+# Combined Example: Org Invitation → Cloud User Org Assignment
+
+This combined example is organized into step subfolders (v1–v3):
+
+- v1/: Initial state with:
+  - a pending `mongodbatlas_org_invitation` (with `teams_ids`), and
+  - an accepted (ACTIVE) user present in the org (no invitation in state).
+- v2/: Migration step showcasing both paths:
+  - moved block for the pending invitation (module-friendly, recommended), and
+  - import blocks for accepted (ACTIVE) users and team assignments.
+- v3/: Cleaned-up final configuration after v2 is applied:
+  - remove the `mongodbatlas_org_invitation` resource,
+  - remove moved and import blocks,
+  - keep only `mongodbatlas_cloud_user_org_assignment` and `mongodbatlas_cloud_user_team_assignment`.
+
+Navigate into each version folder to see the step-specific configuration.

examples/migrate_org_invitation_to_cloud_user_org_assignment/v1/README.md

@@ -0,0 +1,5 @@
+# v1: Initial State
+
+State:
+- `mongodbatlas_org_invitation` manages a pending user (with `teams_ids`).
+- An accepted (ACTIVE) user exists in the organization (no invitation in state), referenced via `data.mongodbatlas_organization`.

examples/migrate_org_invitation_to_cloud_user_org_assignment/v1/main.tf

@@ -0,0 +1,29 @@
+############################################################
+# v1: Initial State
+# - One pending invitation managed via mongodbatlas_org_invitation (with teams)
+# - One active user present in org (no invitation resource in state)
+############################################################
+
+# Pending invitation (with teams)
+resource "mongodbatlas_org_invitation" "pending" {
+  org_id    = var.org_id
+  username  = var.pending_username
+  roles     = var.roles
+  teams_ids = var.pending_team_ids
+}
+
+# Active user is represented only for reference via data source
+data "mongodbatlas_organization" "org" {
+  org_id = var.org_id
+}
+
+locals {
+  active_users = {
+    for u in data.mongodbatlas_organization.org.users :
+    u.username => u if u.org_membership_status == "ACTIVE" && u.username == var.active_username
+  }
+}
+
+output "active_users" {
+  value = local.active_users
+}

examples/migrate_org_invitation_to_cloud_user_org_assignment/v1/provider.tf

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

examples/migrate_org_invitation_to_cloud_user_org_assignment/v1/variables.tf

@@ -0,0 +1,24 @@
+variable "public_key" {
+  type    = string
+  default = ""
+}
+variable "private_key" {
+  type    = string
+  default = ""
+}
+
+variable "org_id" { type = string }
+# Pending invite user
+variable "pending_username" { type = string }
+variable "roles" {
+  type    = set(string)
+  default = ["ORG_MEMBER"]
+}
+# Teams for pending invite
+variable "pending_team_ids" {
+  type    = set(string)
+  default = []
+}
+
+# Active user already in org (no invitation resource remains in state)
+variable "active_username" { type = string }

examples/migrate_org_invitation_to_cloud_user_org_assignment/v1/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.5.0"
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.0"
+    }
+  }
+}

examples/migrate_org_invitation_to_cloud_user_org_assignment/v2/README.md

@@ -0,0 +1,6 @@
+# v2: Migrate using Moved and Import blocks
+
+State:
+- Pending invitation → move state from `mongodbatlas_org_invitation` to `mongodbatlas_cloud_user_org_assignment` using a Terraform `moved` block (no recreate).
+- Accepted (ACTIVE) user → declare the resource and use `import` blocks to adopt the existing assignment (`org_id,user_id`).
+- Teams → manage memberships via `mongodbatlas_cloud_user_team_assignment`; import existing mappings (`org_id,team_id,user_id`).

examples/migrate_org_invitation_to_cloud_user_org_assignment/v2/main.tf

@@ -0,0 +1,58 @@
+############################################################
+# v2: Migration
+# - Pending invitation → cloud_user_org_assignment via moved block
+# - Demonstrate import path for ACTIVE users and team assignments
+############################################################
+
+# New resource + moved block (recommended)
+resource "mongodbatlas_cloud_user_org_assignment" "pending" {
+  org_id   = var.org_id
+  username = var.pending_username
+  roles    = { org_roles = var.roles }
+}
+
+moved {
+  from = mongodbatlas_org_invitation.pending
+  to   = mongodbatlas_cloud_user_org_assignment.pending
+}
+
+# Import ACTIVE users discovered via data source
+data "mongodbatlas_organization" "org" {
+  org_id = var.org_id
+}
+
+locals {
+  active_users = {
+    for u in data.mongodbatlas_organization.org.users :
+    u.id => u if u.org_membership_status == "ACTIVE" && u.username == var.active_username
+  }
+}
+
+resource "mongodbatlas_cloud_user_org_assignment" "active" {
+  for_each = local.active_users
+
+  org_id   = var.org_id
+  username = each.value.username
+  roles    = { org_roles = each.value.roles[0].org_roles }
+}
+
+import {
+  for_each = local.active_users
+  to       = mongodbatlas_cloud_user_org_assignment.active[each.key]
+  id       = "${var.org_id}/${each.key}"
+}
+
+# Team assignments for the pending user (after moved/import)
+resource "mongodbatlas_cloud_user_team_assignment" "teams" {
+  for_each = var.pending_team_ids
+
+  org_id  = var.org_id
+  team_id = each.key
+  user_id = mongodbatlas_cloud_user_org_assignment.pending.user_id
+}
+
+import {
+  for_each = var.pending_team_ids
+  to       = mongodbatlas_cloud_user_team_assignment.teams[each.key]
+  id       = "${var.org_id}/${each.key}/${var.pending_username}"
+}

examples/migrate_org_invitation_to_cloud_user_org_assignment/v2/provider.tf

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