|
| 1 | +--- |
| 2 | +page_title: "Migration Guide: Org Invitation to Cloud User Org Assignment" |
| 3 | +--- |
| 4 | + |
| 5 | +# Migration Guide: Org Invitation to Cloud User Org Assignment |
| 6 | + |
| 7 | +**Objective**: Migrate from the deprecated `mongodbatlas_org_invitation` resource and data source to the `mongodbatlas_cloud_user_org_assignment` resource. If you previously assigned teams via `teams_ids`, also migrate those to `mongodbatlas_cloud_user_team_assignment`. |
| 8 | + |
| 9 | +## Before you begin |
| 10 | + |
| 11 | +- Back up your Terraform state file. |
| 12 | +- Ensure you are using the MongoDB Atlas Terraform Provider 2.0.0 version that includes `mongodbatlas_cloud_user_org_assignment` and `mongodbatlas_cloud_user_team_assignment` resources. |
| 13 | + |
| 14 | +## What’s changing? |
| 15 | + |
| 16 | +- `mongodbatlas_org_invitation` only managed invitations and is deprecated. It didn’t manage the actual user membership or expose `user_id`. |
| 17 | +- `mongodbatlas_cloud_user_org_assignment` manages the user’s organization membership (pending or active) and exposes both `username` and `user_id`. It supports import using either `ORG_ID/USERNAME` or `ORG_ID/USER_ID`. |
| 18 | +- If you previously used `teams_ids` on invitations, use `mongodbatlas_cloud_user_team_assignment` to manage team membership per user and team. |
| 19 | + |
| 20 | +--- |
| 21 | + |
| 22 | +## Use-case 1: Existing org invite is still PENDING (resource exists in config) |
| 23 | + |
| 24 | +Original configuration (note: `user_id` does not exist on `mongodbatlas_org_invitation`): |
| 25 | + |
| 26 | +```terraform |
| 27 | +locals { |
| 28 | + org_id = "<ORG_ID>" |
| 29 | + |
| 30 | + roles = ["ORG_MEMBER"] |
| 31 | +} |
| 32 | +
|
| 33 | +resource "mongodbatlas_org_invitation" "this" { |
| 34 | + username = local.username |
| 35 | + org_id = local.org_id |
| 36 | + roles = local.roles |
| 37 | + # teams_ids = local.team_ids # if applicable |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +### Option A) [Recommended] Moved block |
| 42 | + |
| 43 | +#### Step 1: Add `mongodbatlas_cloud_user_org_assignment` and `moved` block |
| 44 | + |
| 45 | +Handling migration in modules: |
| 46 | +- For module maintainers: Add the new `mongodbatlas_cloud_user_org_assignment` resource inside the module, include a `moved {}` block from `mongodbatlas_org_invitation` to the new resource, and publish a new module version. |
| 47 | +- For module users: Simply bump the module version and run `terraform init -upgrade`, then `terraform plan` / `terraform apply`. Terraform performs an in-place state move without users writing import blocks or touching state. |
| 48 | +- Works at any scale (any number of module instances) and keeps the migration self-contained within the module. No per-environment import steps are required. |
| 49 | + |
| 50 | +```terraform |
| 51 | +resource "mongodbatlas_cloud_user_org_assignment" "this" { |
| 52 | + org_id = local.org_id |
| 53 | + username = local.username |
| 54 | + roles = { org_roles = local.roles } |
| 55 | +} |
| 56 | +
|
| 57 | +moved { |
| 58 | + from = mongodbatlas_org_invitation.this |
| 59 | + to = mongodbatlas_cloud_user_org_assignment.this |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +#### Step 2: Remove `mongodbatlas_org_invitation` from config and state |
| 64 | + |
| 65 | +- With a moved block, `terraform plan` should show the move and no other changes. Then `terraform apply`. |
| 66 | + |
| 67 | + |
| 68 | +### Option B) Import by username |
| 69 | + |
| 70 | +#### Step 1: Add `mongodbatlas_cloud_user_org_assignment` and `import` block |
| 71 | + |
| 72 | +Handling migration in modules: |
| 73 | +- Terraform import blocks cannot live inside modules; they must be defined in the root module. See `https://github.com/hashicorp/terraform/issues/33474`. |
| 74 | +- Module maintainers cannot ship import steps. Each module user must add root-level import blocks for every instance to import, which is error-prone and repetitive. |
| 75 | +- This creates extra coordination for every environment and workspace. Prefer Option A whenever you can modify the module source. |
| 76 | + |
| 77 | +```terraform |
| 78 | +resource "mongodbatlas_cloud_user_org_assignment" "this" { |
| 79 | + org_id = local.org_id |
| 80 | + username = local.username |
| 81 | + roles = { org_roles = local.roles } |
| 82 | +} |
| 83 | +
|
| 84 | +import { |
| 85 | + to = mongodbatlas_cloud_user_org_assignment.this |
| 86 | + id = "${local.org_id}/${local.username}" |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +#### Step 2: Remove `mongodbatlas_org_invitation` from config and state |
| 91 | + |
| 92 | +- With import, remove the old `mongodbatlas_org_invitation` block and delete it from state if still present: `terraform state rm mongodbatlas_org_invitation.this`. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## Use-case 2: Invitations already ACCEPTED (no `mongodbatlas_org_invitation` in config) |
| 97 | + |
| 98 | +When an invite is accepted, Atlas deletes the underlying invitation. To manage these users going forward, import them into `mongodbatlas_cloud_user_org_assignment`. |
| 99 | + |
| 100 | +### Step 1: Fetch active org users (optional helper) |
| 101 | + |
| 102 | +```terraform |
| 103 | +data "mongodbatlas_organization" "org" { |
| 104 | + org_id = var.org_id |
| 105 | +} |
| 106 | +
|
| 107 | +locals { |
| 108 | + active_users = { |
| 109 | + for u in data.mongodbatlas_organization.org.users : |
| 110 | + u.id => u if u.org_membership_status == "ACTIVE" |
| 111 | + } |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +### Step 2: Define and import `mongodbatlas_cloud_user_org_assignment` |
| 116 | + |
| 117 | +Handling migration in modules: |
| 118 | +- Terraform import blocks cannot live inside modules; they must be defined in the root module. See `https://github.com/hashicorp/terraform/issues/33474`. |
| 119 | + |
| 120 | +Use the `local.active_users` map defined in Step 1 so you don’t have to manually curate a list: |
| 121 | + |
| 122 | +```terraform |
| 123 | +resource "mongodbatlas_cloud_user_org_assignment" "user" { |
| 124 | + for_each = local.active_users # key = user_id, value = user object from data source |
| 125 | +
|
| 126 | + org_id = var.org_id |
| 127 | + username = each.value.username |
| 128 | +
|
| 129 | + # Keep roles aligned with current assignments to avoid drift after import |
| 130 | + roles = { |
| 131 | + org_roles = each.value.roles[0].org_roles |
| 132 | + } |
| 133 | +} |
| 134 | +
|
| 135 | +# Import existing users (root module only) |
| 136 | +import { |
| 137 | + for_each = local.active_users |
| 138 | + to = mongodbatlas_cloud_user_org_assignment.user[each.key] |
| 139 | + id = "${var.org_id}/${each.key}" # org_id/user_id |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +Run `terraform plan` (you should see import operations), then `terraform apply`. |
| 144 | + |
| 145 | +--- |
| 146 | + |
| 147 | +## Use-case 3: You also set `teams_ids` on the original invitation |
| 148 | + |
| 149 | +Original configuration where `mongodbatlas_org_invitation` defines `teams_ids`: |
| 150 | + |
| 151 | +```terraform |
| 152 | +locals { |
| 153 | + org_id = "<ORG_ID>" |
| 154 | + |
| 155 | + roles = ["ORG_MEMBER"] |
| 156 | +} |
| 157 | +
|
| 158 | +resource "mongodbatlas_org_invitation" "this" { |
| 159 | + username = local.username |
| 160 | + org_id = local.org_id |
| 161 | + roles = local.roles |
| 162 | + teams_ids = local.team_ids |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +Migrate team assignments to `mongodbatlas_cloud_user_team_assignment` in addition to Use-case 1 or 2 above. |
| 167 | + |
| 168 | +```terraform |
| 169 | +variable "team_ids" { type = set(string) } |
| 170 | +
|
| 171 | +resource "mongodbatlas_cloud_user_team_assignment" "team" { |
| 172 | + for_each = var.team_ids |
| 173 | +
|
| 174 | + org_id = local.org_id |
| 175 | + team_id = each.key |
| 176 | + user_id = mongodbatlas_cloud_user_org_assignment.this.id |
| 177 | +} |
| 178 | +
|
| 179 | +# Import existing team assignments (root module only) |
| 180 | +import { |
| 181 | + for_each = var.team_ids |
| 182 | + to = mongodbatlas_cloud_user_team_assignment.team[each.key] |
| 183 | + id = "${local.org_id}/${each.key}/${local.username}" # OR use user_id in place of username |
| 184 | +} |
| 185 | +``` |
| 186 | + |
| 187 | +Run `terraform plan` (you should see import operations), then `terraform apply`. |
| 188 | + |
| 189 | +Finally, remove any remaining `mongodbatlas_org_invitation` references from config and state. |
| 190 | + |
| 191 | +--- |
| 192 | + |
| 193 | +## Data source migration |
| 194 | + |
| 195 | +Original configuration: |
| 196 | + |
| 197 | +```terraform |
| 198 | +locals { |
| 199 | + org_id = "<ORG_ID>" |
| 200 | + |
| 201 | +} |
| 202 | +
|
| 203 | +data "mongodbatlas_org_invitation" "test" { |
| 204 | + org_id = local.org_id |
| 205 | + username = local.username |
| 206 | + invitation_id = mongodbatlas_org_invitation.test.invitation_id |
| 207 | +} |
| 208 | +``` |
| 209 | + |
| 210 | +Replace with the new data source: |
| 211 | + |
| 212 | +```terraform |
| 213 | +data "mongodbatlas_cloud_user_org_assignment" "user_1" { |
| 214 | + org_id = local.org_id |
| 215 | + username = local.username |
| 216 | +} |
| 217 | +``` |
| 218 | + |
| 219 | +Then: |
| 220 | + |
| 221 | +1. Run `terraform apply` to ensure the new data source reads correctly. |
| 222 | +2. Replace all usages of `data.mongodbatlas_org_invitation.test` with `data.mongodbatlas_cloud_user_org_assignment.user_1`. |
| 223 | +3. Run `terraform plan` followed by `terraform apply`. |
| 224 | + |
| 225 | +--- |
| 226 | + |
| 227 | +## Notes and tips |
| 228 | + |
| 229 | +- Import formats: |
| 230 | + - Org assignment: `ORG_ID/USERNAME` or `ORG_ID/USER_ID`. |
| 231 | + - Team assignment: `ORG_ID/TEAM_ID/USERNAME` or `ORG_ID/TEAM_ID/USER_ID`. |
| 232 | +- If you use modules, keep in mind import blocks must be placed at the root module. |
| 233 | +- After successful migration, ensure no references to `mongodbatlas_org_invitation` remain. |
| 234 | + |
0 commit comments