chore: Deprecates User and Invitations resources, data sources and attributes (#3613)

Author: oarbusi

.changelog/3613.txt

@@ -0,0 +1,43 @@
+```release-note:note
+data-source/mongodbatlas_atlas_user: Deprecates the data source
+```
+
+```release-note:note
+data-source/mongodbatlas_atlas_users: Deprecates the data source
+```
+
+```release-note:note
+data-source/mongodbatlas_atlas_user: Deprecates `email_address` attribute
+```
+
+```release-note:note
+data-source/mongodbatlas_atlas_users: Deprecates `results.email_address` attribute
+```
+
+```release-note:note
+resource/mongodbatlas_org_invitation: Deprecates the resource
+```
+
+```release-note:note
+data-source/mongodbatlas_org_invitation: Deprecates the data source
+```
+
+```release-note:note
+resource/mongodbatlas_project_invitation: Deprecates the resource
+```
+
+```release-note:note
+data-source/mongodbatlas_project_invitation: Deprecates the data source
+```
+
+```release-note:note
+resource/mongodbatlas_project: Deprecates `teams` attribute
+```
+
+```release-note:note
+data-source/mongodbatlas_project: Deprecates `teams` attribute
+```
+
+```release-note:note
+data-source/mongodbatlas_projects: Deprecates `results.teams` attribute
+```

docs/data-sources/atlas_user.md

@@ -1,3 +1,7 @@
+---
+subcategory: "Deprecated"    
+---
+
 # Data Source: mongodbatlas_atlas_user
 
 `mongodbatlas_atlas_user` Provides a MongoDB Atlas User.
@@ -34,7 +38,7 @@ data "mongodbatlas_atlas_user" "test" {
 In addition to all arguments above, the following attributes are exported:
 * `country` - Two alphabet characters that identifies MongoDB Atlas user's geographic location. This parameter uses the ISO 3166-1a2 code format.
 * `created_at` - Date and time when the current account is created. This value is in the ISO 8601 timestamp format in UTC.
-* `email_address` - Email address that belongs to the MongoDB Atlas user.
+* `email_address` - **(DEPRECATED)** Email address that belongs to the MongoDB Atlas user.
 * `first_name` - First or given name that belongs to the MongoDB Atlas user.
 * `last_auth` - Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
 * `last_name` - Last name, family name, or surname that belongs to the MongoDB Atlas user.

docs/data-sources/atlas_users.md

@@ -1,3 +1,7 @@
+---
+subcategory: "Deprecated"    
+---
+
 # Data Source: atlas_users
 
 `atlas_users` provides Atlas Users associated with a specified Organization, Project, or Team.
@@ -56,7 +60,7 @@ In addition to all arguments above, the following attributes are exported:
 * `username` - Email address that belongs to the MongoDB Atlas user account. You cannot modify this address after creating the user.
 * `country` - Two alphabet characters that identifies MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.
 * `created_at` - Date and time when the current account is created. This value is in the ISO 8601 timestamp format in UTC.
-* `email_address` - Email address that belongs to the MongoDB Atlas user.
+* `email_address` - **(DEPRECATED)** Email address that belongs to the MongoDB Atlas user.
 * `first_name` - First or given name that belongs to the MongoDB Atlas user.
 * `last_auth` - Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
 * `last_name` - Last name, family name, or surname that belongs to the MongoDB Atlas user.

docs/data-sources/org_invitation.md

@@ -1,3 +1,7 @@
+---
+subcategory: "Deprecated"    
+---
+
 # Data Source: mongodbatlas_org_invitation
 
 `mongodbatlas_org_invitation` describes an invitation for a user to join an Atlas organization.

docs/data-sources/project.md

@@ -79,7 +79,7 @@ In addition to all arguments above, the following attributes are exported:
 * `cluster_count` - The number of Atlas clusters deployed in the project.
 * `created` - The ISO-8601-formatted timestamp of when Atlas created the project.
 * `tags` - Map that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the project. To learn more, see [Resource Tags](https://www.mongodb.com/docs/atlas/tags/)
-* `teams` - Returns all teams to which the authenticated user has access in the project. See [Teams](#teams).
+* `teams` - **(DEPRECATED)** Returns all teams to which the authenticated user has access in the project. See [Teams](#teams).
 * `limits` - The limits for the specified project. See [Limits](#limits).
 * `ip_addresses` - IP addresses in a project categorized by services. See [IP Addresses](#ip-addresses). **WARNING:** This attribute is deprecated, use the `mongodbatlas_project_ip_addresses` data source instead.
 * `users` - Returns list of all pending and active MongoDB Cloud users associated with the specified project.
@@ -94,6 +94,8 @@ In addition to all arguments above, the following attributes are exported:
 
 ### Teams
 
+~> **DEPRECATION:** This attribute is deprecated and will be removed in the next major release. Please transition to `mongodbatlas_team_project_assignment`. For more details, see [Migration Guide: Project Teams Attribute to Team Project Assignment Resource](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/team_project_assignment_migration_guide).
+
 * `team_id` - The unique identifier of the team you want to associate with the project. The team and project must share the same parent organization.
 * `role_names` - Each string in the array represents a project role assigned to the team. Every user associated with the team inherits these roles. The [MongoDB Documentation](https://www.mongodb.com/docs/atlas/reference/user-roles/#organization-roles) describes the roles a user can have.
 

docs/data-sources/project_invitation.md

@@ -1,3 +1,6 @@
+---
+subcategory: "Deprecated"    
+---
 # Data Source: mongodbatlas_project_invitation
 
 `mongodbatlas_project_invitation` describes an invitation to a user to join an Atlas project.

docs/data-sources/projects.md

@@ -55,7 +55,7 @@ data "mongodbatlas_projects" "test" {
 * `cluster_count` - The number of Atlas clusters deployed in the project.
 * `created` - The ISO-8601-formatted timestamp of when Atlas created the project.
 * `tags` - Map that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the project. To learn more, see [Resource Tags](https://www.mongodb.com/docs/atlas/tags/)
-* `teams` - Returns all teams to which the authenticated user has access in the project. See [Teams](#teams).
+* `teams` - **(DEPRECATED)** Returns all teams to which the authenticated user has access in the project. See [Teams](#teams).
 * `limits` - The limits for the specified project. See [Limits](#limits).
 * `ip_addresses` - IP addresses in a project categorized by services. See [IP Addresses](#ip-addresses). **WARNING:** This attribute is deprecated, use the `mongodbatlas_project_ip_addresses` data source instead.
 * `users` - Returns list of all pending and active MongoDB Cloud users associated with the specified project.
@@ -70,6 +70,8 @@ data "mongodbatlas_projects" "test" {
 
 ### Teams
 
+~> **DEPRECATION:** This attribute is deprecated and will be removed in the next major release. Please transition to `mongodbatlas_team_project_assignment`. For more details, see [Migration Guide: Project Teams Attribute to Team Project Assignment Resource](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/team_project_assignment_migration_guide).
+
 * `team_id` - The unique identifier of the team you want to associate with the project. The team and project must share the same parent organization.
 * `role_names` - Each string in the array represents a project role assigned to the team. Every user associated with the team inherits these roles. The [MongoDB Documentation](https://www.mongodb.com/docs/atlas/reference/user-roles/#organization-roles) describes the roles a user can have.
 

docs/data-sources/team.md

@@ -50,7 +50,7 @@ In addition to all arguments above, the following attributes are exported:
 * `id` - Terraform's unique identifier used internally for state management.
 * `team_id` -  The unique identifier for the team.
 * `name` -  The name of the team you want to create.
-* `usernames` - The users who are part of the team.
+* `usernames` - **(DEPRECATED)** The users who are part of the team. This attribute is deprecated and will be removed in the next major release. Please transition to `data.mongodbatlas_team.users`. For more details, see [Migration Guide: Team Usernames Attribute to Cloud User Team Assignment](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cloud_user_team_assignment_migration_guide.md).
 * `users`- Returns a list of all pending and active MongoDB Cloud users associated with the specified team.
 
 ### Users

docs/guides/2.0.0-upgrade-guide.md

@@ -8,11 +8,15 @@ MongoDB Atlas Provider 2.0.0: Upgrade and Information Guide
 
 # MongoDB Atlas Provider 2.0.0: Upgrade and Information Guide
 
-The Terraform MongoDB Atlas Provider version 2.0.0 has the following new features and breaking changes:
+The Terraform MongoDB Atlas Provider version 2.0.0 introduces new features, breaking changes, and resource deprecations/removals.
+
+Use this guide to understand what’s new, what requires migration, and how to update your configurations.
 
 ## New Resources, Data Sources, and Features
 
-- **New `delete_on_create_timeout` attribute**: Multiple resources now support a `delete_on_create_timeout` boolean attribute that controls cleanup behavior when resource creation times out. When set to `true` (default), the provider will delete the underlying resource if the create operation times out, helping to avoid orphaned resources. This attribute is available in the following resources:
+### New `delete_on_create_timeout` attribute 
+
+Multiple resources now support a `delete_on_create_timeout` boolean attribute that controls cleanup behavior when resource creation times out. When set to `true` (default), the provider will delete the underlying resource if the create operation times out, helping to avoid orphaned resources. This attribute is available in the following resources:
   - `mongodbatlas_advanced_cluster`
   - `mongodbatlas_cloud_backup_snapshot` 
   - `mongodbatlas_cluster_outage_simulation`
@@ -26,6 +30,14 @@ The Terraform MongoDB Atlas Provider version 2.0.0 has the following new feature
   - `mongodbatlas_search_deployment`
   - `mongodbatlas_stream_processor`
 
+### New Cloud User Assignment Resources 
+
+New user and team management resources that replace deprecated invitation-based workflow:
+  - `mongodbatlas_cloud_user_org_assignment` resource and data source: Manages user membership in organizations with structured roles and support for both pending and active memberships.
+  - `mongodbatlas_cloud_user_project_assignment` resource and data source: Manages user membership in projects with automatic invitation handling based on organization membership status.
+  - `mongodbatlas_cloud_user_team_assignment` resource and data source: Manages user membership in teams with support for both username and user ID.
+  - `mongodbatlas_team_project_assignment` resource and data source: Manages team assignments to projects.
+
 ## Breaking Changes
 
 ### `mongodbatlas_cloud_backup_schedule`
@@ -57,22 +69,46 @@ Data source:
 ## Removed resources & data sources
 
   - `mongodbatlas_cloud_provider_snapshot`
-  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_snapshot` instead
+  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_snapshot` instead.
 
   - `mongodbatlas_cloud_provider_snapshot_backup_policy`
-  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_schedule` instead
+  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_schedule` instead.
 
   - `mongodbatlas_cloud_provider_snapshot_restore_job`
-  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_snapshot_restore_job` instead
+  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_cloud_backup_snapshot_restore_job` instead.
 
   - `mongodbatlas_privatelink_endpoint_serverless`
-  This deprecated resource & data source(s) have been removed. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide)
+  This deprecated resource & data source(s) have been removed. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
 
   - `mongodbatlas_privatelink_endpoint_service_serverless`
-  This deprecated resource & data source(s) have been removed. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide)
+  This deprecated resource & data source(s) have been removed. For more details, see [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
 
   - `mongodbatlas_teams`
-  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_team` instead
+  This deprecated resource & data source(s) have been removed. Please use `mongodbatlas_team` instead.
+
+## Deprecations
+
+Version 2.0.0 introduces several deprecations as part of modernizing the provider's user and invitation management. These deprecated resources and attributes **will be removed in a future major version release**. Migration guides are available to help transition to the recommended replacements:
+
+### Resources and Data sources
+
+- **`mongodbatlas_cluster` resource and data sources**: Deprecated. Use `mongodbatlas_advanced_cluster` resource and data sources instead. See [the Cluster to Advanced Cluster Migration Guide](../guides/cluster-to-advanced-cluster-migration-guide).
+
+- **`mongodbatlas_org_invitation` resource and data source**: Deprecated. Use `mongodbatlas_cloud_user_org_assignment` resource instead. See the [Org Invitation to Cloud User Org Assignment Migration Guide](../guides/org-invitation-to-cloud-user-org-assignment-migration-guide.md) for migration steps.
+
+- **`mongodbatlas_project_invitation` resource and data source**: Deprecated. Use `mongodbatlas_cloud_user_project_assignment` resource instead. See the [Project Invitation to Cloud User Project Assignment Migration Guide](../guides/project-invitation-to-cloud-user-project-assignment-migration-guide.md) for migration steps.
+
+- **`mongodbatlas_atlas_user` data source**: Deprecated. Use `mongodbatlas_cloud_user_org_assignment` data source instead. See the [Migration Guide: Migrate off deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users`](../guides/atlas-user-migration-guide.md) for migration steps.
+
+- **`mongodbatlas_atlas_users` data source**: Deprecated. Use the `users` attribute on `mongodbatlas_organization`, `mongodbatlas_project`, or `mongodbatlas_team` data sources respectively. See the [Migration Guide: Migrate off deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users`](../guides/atlas-user-migration-guide.md) for migration steps.
+
+### Attributes
+
+- **`teams` attribute in `mongodbatlas_project` resource and data source**: Deprecated. Use `mongodbatlas_team_project_assignment` resource and data source to manage team membership to projects. See [Project Teams Attribute to Team Project Assignment Resource Migration Guide](../guides/team_project_assignment_migration_guide) for migration steps.
+
+- **`email_address` attribute in `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users` data sources**: Deprecated. See the [Migration Guide: Migrate off deprecated `mongodbatlas_atlas_user` and `mongodbatlas_atlas_users`](../guides/atlas-user-migration-guide.md) for migration steps.
+
+- **`usernames` attribute in `mongodbatlas_team` resource and data source**: Deprecated. Use `mongodbatlas_cloud_user_team_assignment` resource to manage team membership per user and team. See the [Team Usernames Attribute to Cloud User Team Assignment Migration guide](../guides/cloud_user_team_assignment_migration_guide.md) for migration steps.
 
 2.0.0 also includes general improvements, bug fixes, and several key documentation updates. See the [CHANGELOG](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CHANGELOG.md) for more specific information.
 

docs/resources/org_invitation.md

@@ -1,3 +1,7 @@
+---
+subcategory: "Deprecated"    
+---
+
 # Resource: mongodbatlas_org_invitation
 
 `mongodbatlas_org_invitation` invites a user to join an Atlas organization.