doc: Adds example & documentation for new mongodbatlas_cloud_user_org_assignment resource

.changelog/3486.txt

@@ -0,0 +1,3 @@
+```release-note:new-resource
+resource/mongodbatlas_cloud_user_org_assignment 
+```

.changelog/3491.txt

@@ -0,0 +1,3 @@
+```release-note:new-datasource
+data-source/mongodbatlas_cloud_user_org_assignment 
+```

.github/workflows/acceptance-tests-runner.yml

@@ -244,6 +244,7 @@ jobs:
       autogen: ${{ steps.filter.outputs.autogen == 'true' || env.mustTrigger == 'true' }}
       backup: ${{ steps.filter.outputs.backup == 'true' || env.mustTrigger == 'true' }}
       control_plane_ip_addresses: ${{ steps.filter.outputs.control_plane_ip_addresses == 'true' || env.mustTrigger == 'true' }}
+      cloud_user: ${{ steps.filter.outputs.cloud_user == 'true' || env.mustTrigger == 'true' }}
       cluster: ${{ steps.filter.outputs.cluster == 'true' || env.mustTrigger == 'true' }}
       cluster_outage_simulation: ${{ steps.filter.outputs.cluster_outage_simulation == 'true' || env.mustTrigger == 'true' }}
       config: ${{ steps.filter.outputs.config == 'true' || env.mustTrigger == 'true' }}
@@ -299,6 +300,8 @@ jobs:
             - 'internal/service/onlinearchive/*.go'
           control_plane_ip_addresses:
             - 'internal/service/controlplaneipaddresses/*.go'
+          cloud_user:
+            - 'internal/service/clouduserorgassignment/*.go'
           cluster:
             - 'internal/service/cluster/*.go'
           cluster_outage_simulation:
@@ -589,6 +592,29 @@ jobs:
           MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
           ACCTEST_PACKAGES: ./internal/service/controlplaneipaddresses
         run: make testacc
+
+  cloud_user:
+    needs: [ change-detection, get-provider-version ]
+    if: ${{ needs.change-detection.outputs.cloud_user == 'true' || inputs.test_group == 'cloud_user' }}
+    runs-on: ubuntu-latest
+    permissions: {}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+      - uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5
+        with:
+          go-version-file: 'go.mod'
+      - uses: hashicorp/setup-terraform@b9cd54a3c349d3f38e8881555d616ced269862dd
+        with:
+          terraform_version: ${{ inputs.terraform_version }}
+          terraform_wrapper: false  
+      - name: Acceptance Tests
+        env:
+          MONGODB_ATLAS_LAST_VERSION: ${{ needs.get-provider-version.outputs.provider_version }}
+          MONGODB_ATLAS_TEAMS_IDS: ${{ inputs.mongodb_atlas_teams_ids }}
+          ACCTEST_PACKAGES: ./internal/service/clouduserorgassignment
+        run: make testacc
 
   cluster:
     needs: [ change-detection, get-provider-version ]

docs/data-sources/cloud_user_org_assignment.md

@@ -0,0 +1,74 @@
+# Data Source: mongodbatlas_cloud_user_org_assignment
+
+`mongodbatlas_cloud_user_org_assignment` provides a Cloud User Organization Assignment data source. The data source lets you retrieve a user assigned to an organization.
+
+**NOTE**: Users with pending invitations created using the deprecated`mongodbatlas_project_invitation` resource or via the deprecated [Invite One MongoDB Cloud User to One Project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getorganizationuser#tag/Projects/operation/createProjectInvitation) 
+endpoint are not returned with this resource. See  [MongoDB Atlas API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getorganizationuser) for details. 
+To manage such users with this resource, refer to our [migration guide]<link-to-migration-guide>.
+
+## Example Usages
+
+```terraform
+resource "mongodbatlas_cloud_user_org_assignment" "example" {
+  org_id   = var.org_id
+  username = var.user_email
+  roles = {
+    org_roles = ["ORG_MEMBER"]
+  }
+} 
+
+data "mongodbatlas_cloud_user_org_assignment" "example_username" {
+  org_id   = var.org_id
+  username = var.user_email
+}
+
+data "mongodbatlas_cloud_user_org_assignment" "example_user_id" {
+  org_id   = var.org_id
+  user_id  = var.user_id
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `org_id` (String) Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the [/orgs](#tag/Organizations/operation/listOrganizations) endpoint to retrieve all organizations to which the authenticated user has access.
+
+### Optional
+
+- `user_id` (String) Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user.
+- `username` (String) Email address that represents the username of the MongoDB Cloud user.
+
+### Read-Only
+
+- `country` (String) Two-character alphabetical string that identifies the MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.
+- `created_at` (String) Date and time when MongoDB Cloud created the current account. This value is in the ISO 8601 timestamp format in UTC.
+- `first_name` (String) First or given name that belongs to the MongoDB Cloud user.
+- `invitation_created_at` (String) Date and time when MongoDB Cloud sent the invitation. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+- `invitation_expires_at` (String) Date and time when the invitation from MongoDB Cloud expires. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+- `inviter_username` (String) Username of the MongoDB Cloud user who sent the invitation to join the organization.
+- `last_auth` (String) Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
+- `last_name` (String) Last name, family name, or surname that belongs to the MongoDB Cloud user.
+- `mobile_number` (String) Mobile phone number that belongs to the MongoDB Cloud user.
+- `org_membership_status` (String) String enum that indicates whether the MongoDB Cloud user has a pending invitation to join the organization or they are already active in the organization.
+- `roles` (Attributes) Organization and project level roles to assign the MongoDB Cloud user within one organization. (see [below for nested schema](#nestedatt--roles))
+- `team_ids` (Set of String) List of unique 24-hexadecimal digit strings that identifies the teams to which this MongoDB Cloud user belongs.
+
+<a id="nestedatt--roles"></a>
+### Nested Schema for `roles`
+
+Read-Only:
+
+- `org_roles` (Set of String) One or more organization level roles to assign the MongoDB Cloud user.
+- `project_role_assignments` (Attributes List) List of project level role assignments to assign the MongoDB Cloud user. (see [below for nested schema](#nestedatt--roles--project_role_assignments))
+
+<a id="nestedatt--roles--project_role_assignments"></a>
+### Nested Schema for `roles.project_role_assignments`
+
+Read-Only:
+
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies the project to which these roles belong.
+- `project_roles` (Set of String) One or more project-level roles assigned to the MongoDB Cloud user.
+
+For more information see: [MongoDB Atlas API - Cloud Users](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getorganizationuser) Documentation.

docs/resources/cloud_user_org_assignment.md

@@ -0,0 +1,84 @@
+# Resource: mongodbatlas_cloud_user_org_assignment
+
+`mongodbatlas_cloud_user_org_assignment` provides a Cloud User Organization Assignment resource. The resource lets you import, assign, remove, update a user to an organization.
+
+**NOTE**: Users with pending invitations created using the deprecated `mongodbatlas_project_invitation` resource or via the deprecated [Invite One MongoDB Cloud User to One Project](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getorganizationuser#tag/Projects/operation/createProjectInvitation) 
+endpoint cannot be managed with this resource. See [MongoDB Atlas API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-getorganizationuser) for details. 
+To manage such users with this resource, refer to our [migration guide]<link-to-migration-guide>.
+
+## Example Usages
+
+```terraform
+resource "mongodbatlas_cloud_user_org_assignment" "example" {
+  org_id   = var.org_id
+  username = var.user_email
+  roles = {
+    org_roles = ["ORG_MEMBER"]
+  }
+} 
+
+data "mongodbatlas_cloud_user_org_assignment" "example_username" {
+  org_id   = var.org_id
+  username = var.user_email
+}
+
+data "mongodbatlas_cloud_user_org_assignment" "example_user_id" {
+  org_id   = var.org_id
+  user_id  = var.user_id
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `org_id` (String) Unique 24-hexadecimal digit string that identifies the organization that contains your projects. Use the [/orgs](#tag/Organizations/operation/listOrganizations) endpoint to retrieve all organizations to which the authenticated user has access.
+- `roles` (Attributes) Organization and project level roles to assign the MongoDB Cloud user within one organization. (see [below for nested schema](#nestedatt--roles))
+- `username` (String) Email address that represents the username of the MongoDB Cloud user.
+
+### Read-Only
+
+- `country` (String) Two-character alphabetical string that identifies the MongoDB Cloud user's geographic location. This parameter uses the ISO 3166-1a2 code format.
+- `created_at` (String) Date and time when MongoDB Cloud created the current account. This value is in the ISO 8601 timestamp format in UTC.
+- `first_name` (String) First or given name that belongs to the MongoDB Cloud user.
+- `invitation_created_at` (String) Date and time when MongoDB Cloud sent the invitation. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+- `invitation_expires_at` (String) Date and time when the invitation from MongoDB Cloud expires. MongoDB Cloud represents this timestamp in ISO 8601 format in UTC.
+- `inviter_username` (String) Username of the MongoDB Cloud user who sent the invitation to join the organization.
+- `last_auth` (String) Date and time when the current account last authenticated. This value is in the ISO 8601 timestamp format in UTC.
+- `last_name` (String) Last name, family name, or surname that belongs to the MongoDB Cloud user.
+- `mobile_number` (String) Mobile phone number that belongs to the MongoDB Cloud user.
+- `org_membership_status` (String) String enum that indicates whether the MongoDB Cloud user has a pending invitation to join the organization or they are already active in the organization.
+- `team_ids` (Set of String) List of unique 24-hexadecimal digit strings that identifies the teams to which this MongoDB Cloud user belongs.
+- `user_id` (String) Unique 24-hexadecimal digit string that identifies the MongoDB Cloud user.
+
+<a id="nestedatt--roles"></a>
+### Nested Schema for `roles`
+
+Optional:
+
+- `org_roles` (Set of String) One or more organization level roles to assign the MongoDB Cloud user.
+
+Read-Only:
+
+- `project_role_assignments` (Attributes List) List of project level role assignments to assign the MongoDB Cloud user. (see [below for nested schema](#nestedatt--roles--project_role_assignments))
+
+<a id="nestedatt--roles--project_role_assignments"></a>
+### Nested Schema for `roles.project_role_assignments`
+
+Read-Only:
+
+- `project_id` (String) Unique 24-hexadecimal digit string that identifies the project to which these roles belong.
+- `project_roles` (Set of String) One or more project-level roles assigned to the MongoDB Cloud user.
+
+## Import 
+
+Cloud User Org Assignment resource can be imported using the Org ID & Username OR Org ID & User ID, in the format `ORG_ID/USERNAME` OR `ORG_ID/USER_ID`.
+
+```
+$ terraform import mongodbatlas_cloud_user_org_assignment.test 63cfbf302333a3011d98592e/[email protected]
+OR
+$ terraform import mongodbatlas_cloud_user_org_assignment.test 63cfbf302333a3011d98592e/5f18367ccb7a503a2b481b7a
+```
+
+For more information see: [MongoDB Atlas API - Cloud Users](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createorganizationuser) Documentation.

examples/mongodbatlas_cloud_user_org_assignment/README.md

@@ -0,0 +1,29 @@
+# Example: mongodbatlas_cloud_user_org_assignment
+
+This example demonstrates how to use the `mongodbatlas_cloud_user_org_assignment` resource to assign a user to an existing organization with specified roles in MongoDB Atlas.
+
+## Usage
+
+```hcl
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+resource "mongodbatlas_cloud_user_org_assignment" "example" {
+  org_id   = var.org_id
+  username = var.user_email
+  roles = {
+    org_roles = ["ORG_MEMBER"]
+  }
+}
+```
+
+You must set the following variables:
+
+- `public_key`: Your MongoDB Atlas API public key.
+- `private_key`: Your MongoDB Atlas API private key.
+- `org_id`: The ID of the organization to assign the user to.
+- `user_email`: The email address of the user to assign.
+
+To learn more, see the [MongoDB Cloud Users Documentation](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-createorganizationuser).

examples/mongodbatlas_cloud_user_org_assignment/main.tf

@@ -0,0 +1,17 @@
+resource "mongodbatlas_cloud_user_org_assignment" "example" {
+  org_id   = var.org_id
+  username = var.user_email
+  roles = {
+    org_roles = ["ORG_MEMBER"]
+  }
+} 
+
+data "mongodbatlas_cloud_user_org_assignment" "example_username" {
+  org_id   = var.org_id
+  username = var.user_email
+}
+
+data "mongodbatlas_cloud_user_org_assignment" "example_user_id" {
+  org_id   = var.org_id
+  user_id  = var.user_id
+}

examples/mongodbatlas_cloud_user_org_assignment/outputs.tf

@@ -0,0 +1,14 @@
+output "user_from_username" {
+  description = "User details retrieved by username"
+  value = data.mongodbatlas_cloud_user_org_assignment.example_username
+}
+
+output "user_from_user_id" {
+  description = "User details retrieved by user_id"
+  value = data.mongodbatlas_cloud_user_org_assignment.example_user_id
+}
+
+output "created_user" {
+  description = "Details of the created user"
+  value = mongodbatlas_cloud_user_org_assignment.example
+}

examples/mongodbatlas_cloud_user_org_assignment/provider.tf

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

examples/mongodbatlas_cloud_user_org_assignment/variables.tf

@@ -0,0 +1,24 @@
+variable "org_id" {
+  description = "The MongoDB Atlas organization ID"
+  type        = string
+}
+
+variable "user_email" {
+  description = "The email address of the user"
+  type        = string
+}
+
+variable "user_id" {
+  description = "The user ID"
+  type        = string
+}
+
+variable "public_key" {
+  description = "Atlas API public key"
+  type        = string
+}
+
+variable "private_key" {
+  description = "Atlas API private key"
+  type        = string
+}

examples/mongodbatlas_cloud_user_org_assignment/versions.tf

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

internal/common/conversion/collections.go

@@ -1,6 +1,12 @@
 package conversion
 
-import "reflect"
+import (
+	"context"
+	"reflect"
+
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
 
 // HasElementsSliceOrMap checks if param is a non-empty slice or map
 func HasElementsSliceOrMap(value any) bool {
@@ -22,3 +28,11 @@ func ToAnySlicePointer(value *[]map[string]any) *[]any {
 	}
 	return &ret
 }
+
+func TFSetValueOrNull[T any](ctx context.Context, ptr *[]T, elemType attr.Type) types.Set {
+	if ptr == nil || len(*ptr) == 0 {
+		return types.SetNull(elemType)
+	}
+	set, _ := types.SetValueFrom(ctx, elemType, *ptr)
+	return set
+}

internal/common/conversion/collections_test.go

@@ -3,8 +3,10 @@ package conversion_test
 import (
 	"testing"
 
-	"github.com/mongodb/terraform-provider-mongodbatlas/internal/common/conversion"
+	"github.com/hashicorp/terraform-plugin-framework/types"
 	"github.com/stretchr/testify/assert"
+
+	"github.com/mongodb/terraform-provider-mongodbatlas/internal/common/conversion"
 )
 
 func TestHasElementsSliceOrMap(t *testing.T) {
@@ -61,3 +63,25 @@ func TestToAnySlicePointer(t *testing.T) {
 		})
 	}
 }
+
+func TestTFSetValueOrNull(t *testing.T) {
+	ctx := t.Context()
+
+	testCases := map[string]*[]string{
+		"nil":       nil,
+		"empty":     {},
+		"populated": {"a", "b", "c"},
+	}
+
+	for name, value := range testCases {
+		t.Run(name, func(t *testing.T) {
+			result := conversion.TFSetValueOrNull(ctx, value, types.StringType)
+			if value == nil || len(*value) == 0 {
+				assert.True(t, result.IsNull())
+			} else {
+				assert.False(t, result.IsNull())
+				assert.Len(t, result.Elements(), len(*value))
+			}
+		})
+	}
+}

internal/common/schemafunc/attr.go

@@ -0,0 +1,11 @@
+package schemafunc
+
+import "github.com/hashicorp/terraform-plugin-go/tftypes"
+
+func GetAttrFromStateObj[T any](rawState map[string]tftypes.Value, attrName string) *T {
+	var ret *T
+	if err := rawState[attrName].As(&ret); err != nil {
+		return nil
+	}
+	return ret
+}