[Feature] Add datasource databricks_users

NEXT_CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### New Features and Improvements
 
+* Add `databricks_users` data source ([#4028](https://github.com/databricks/terraform-provider-databricks/pull/4028))
+
 ### Bug Fixes
 
 ### Documentation

docs/data-sources/users.md

@@ -0,0 +1,99 @@
+---
+subcategory: "Security"
+---
+
+# databricks_users Data Source
+
+-> This data source works with both the account-level and workspace-level provider. 
+
+-> If you have a fully automated setup with workspaces created by [databricks_mws_workspaces](../resources/mws_workspaces.md) or [azurerm_databricks_workspace](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/databricks_workspace), please make sure to add [depends_on attribute](../guides/troubleshooting.md#data-resources-and-authentication-is-not-configured-errors) in order to prevent _default auth: cannot configure default credentials_ errors.
+
+Retrieves information about multiple [databricks_user](../resources/user.md) resources.
+
+## Example Usage
+
+Adding a subset of users to a group
+
+```hcl
+data "databricks_users" "company_users" {
+  filter = "userName co \"@domain.org\""
+}
+
+resource "databricks_group" "data_users_group" {
+  display_name = "Data Users"
+}
+
+resource "databricks_group_member" "add_users_to_group" {
+  for_each = { for user in data.databricks_users.company_users.users : user.id => user }
+  group_id  = databricks_group.data_users_group.id
+  member_id = each.value.id
+}
+```
+
+## Argument Reference
+
+This data source allows you to filter the list of users using the following optional arguments: 
+
+-> Attribute names and operators used in filters are case-insensitive. Find more information [here](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2).  
+
+- `filter` - (Optional) Query by which the results have to be filtered. If not specified, all users will be returned. Supported operators are equals (`eq`), contains (`co`), starts with (`sw`), and not equals (`ne`). Additionally, simple expressions can be formed using logical operators `and` and `or`.
+
+  **Examples:**
+    - User whose `displayName` equals "john": 
+    ```hcl
+      filter = "displayName eq \"john\""
+    ```
+    - User whose `displayName` contains "john" or `userName` contains "@domain.org": 
+    ```hcl
+      filter = "displayName co \"john\" or userName co \"@domain.org\""
+    ```
+
+- `extra_attributes` - (Optional) A comma-separated list of additional user attributes to include in the results. By default, the data source returns the following attributes: `id`, `userName`, `displayName`, and `externalId`. Use this argument to request additional attributes as needed. The list of all available attributes can be found in the [API reference](https://docs.databricks.com/api/workspace/users/list). 
+
+## Attribute Reference
+
+This data source exposes the following attributes:
+
+- `users` - A list of users matching the specified criteria. Each user has the following attributes:
+    - `id` - The ID of the user.
+    - `userName` - The username of the user.
+    - `emails` - All the emails associated with the Databricks user.
+    - `name`
+      - `givenName` - Given name of the Databricks user.
+      - `familyName` - Family name of the Databricks user.
+    - `displayName` - The display name of the user. 
+    - `groups` - Indicates if the user is part of any groups. 
+      - `$ref`
+      - `value`
+      - `display`
+      - `primary`
+      - `type`
+    - `entitlements` - Entitlements assigned to the user. 
+      - `$ref`
+      - `value`
+      - `display`
+      - `primary`
+      - `type`
+    - `roles` - Indicates if the user has any associated roles.
+      - `$ref`
+      - `value`
+      - `display`
+      - `primary`
+      - `type`
+    - `schemas` - The schema of the user. 
+    - `externalId` - Reserved for future use. 
+    - `active` - Boolean that represents if this user is active. 
+
+## Related Resources
+
+The following resources are used in the same context:
+
+- [**databricks_user**](../resources/user.md): Resource to manage individual users in Databricks.
+
+- [**databricks_group**](../resources/group.md): Resource to manage groups in Databricks.
+
+- [**databricks_group_member**](../resources/group_member.md): Resource to manage group memberships by adding users to groups.
+
+- [**databricks_permissions**](../resources/permissions.md): Resource to manage access control in the Databricks workspace.
+
+- [**databricks_current_user**](current_user.md): Data source to retrieve information about the user or service principal that is calling the Databricks REST API.

internal/providers/pluginfw/pluginfw_rollout_utils.go

@@ -22,6 +22,7 @@ import (
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/products/registered_model"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/products/serving"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/products/sharing"
+	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/products/user"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/products/volume"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
@@ -50,7 +51,6 @@ var pluginFwOnlyResources = append(
 	autoGeneratedResources...,
 )
 
-// List of data sources that have been onboarded to the plugin framework - not migrated from sdkv2.
 // Keep this list sorted.
 var pluginFwOnlyDataSources = append(
 	[]func() datasource.DataSource{
@@ -62,6 +62,7 @@ var pluginFwOnlyDataSources = append(
 		registered_model.DataSourceRegisteredModel,
 		registered_model.DataSourceRegisteredModelVersions,
 		serving.DataSourceServingEndpoints,
+		user.DataSourceUsers,
 		// TODO: Add DataSourceCluster into migratedDataSources after fixing unit tests.
 		cluster.DataSourceCluster, // Using the staging name (with pluginframework suffix)
 		sharing.DataSourceShare,   // Using the staging name (with pluginframework suffix)

internal/providers/pluginfw/products/user/data_users.go

@@ -0,0 +1,104 @@
+package user
+
+import (
+	"context"
+
+	"github.com/databricks/databricks-sdk-go/service/iam"
+	"github.com/databricks/terraform-provider-databricks/common"
+	pluginfwcommon "github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/common"
+	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/converters"
+	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/tfschema"
+	"github.com/databricks/terraform-provider-databricks/internal/service/iam_tf"
+	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+const dataSourceName = "users"
+
+func DataSourceUsers() datasource.DataSource {
+	return &UsersDataSource{}
+}
+
+var _ datasource.DataSourceWithConfigure = &UsersDataSource{}
+
+type UsersDataSource struct {
+	Client *common.DatabricksClient
+}
+
+type UsersInfo struct {
+	Filter          types.String  `json:"filter,omitempty"`
+	ExtraAttributes types.String  `json:"extra_attributes,omitempty"`
+	Users           []iam_tf.User `json:"users,omitempty" tf:"computed"`
+}
+
+func (d *UsersDataSource) Metadata(ctx context.Context, req datasource.MetadataRequest, resp *datasource.MetadataResponse) {
+	resp.TypeName = pluginfwcommon.GetDatabricksProductionName(dataSourceName)
+}
+
+func (d *UsersDataSource) Schema(ctx context.Context, req datasource.SchemaRequest, resp *datasource.SchemaResponse) {
+	attrs, blocks := tfschema.DataSourceStructToSchemaMap(UsersInfo{}, nil)
+	resp.Schema = schema.Schema{
+		Attributes: attrs,
+		Blocks:     blocks,
+	}
+}
+
+func (d *UsersDataSource) Configure(_ context.Context, req datasource.ConfigureRequest, resp *datasource.ConfigureResponse) {
+	if d.Client == nil {
+		d.Client = pluginfwcommon.ConfigureDataSource(req, resp)
+	}
+}
+
+func (d *UsersDataSource) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {
+	var usersInfo UsersInfo
+	attributes := "id,userName,displayName,externalId"
+
+	resp.Diagnostics.Append(req.Config.Get(ctx, &usersInfo)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	if !(usersInfo.ExtraAttributes.IsNull()) {
+		attributes += ","
+		attributes += usersInfo.ExtraAttributes.String()
+	}
+
+	var users []iam.User
+	var err error
+
+	if d.Client.Config.IsAccountClient() {
+		a, diags := d.Client.GetAccountClient()
+		resp.Diagnostics.Append(diags...)
+		if resp.Diagnostics.HasError() {
+			return
+		}
+
+		users, err = a.Users.ListAll(ctx, iam.ListAccountUsersRequest{Filter: usersInfo.Filter.ValueString(), Attributes: attributes})
+		if err != nil {
+			resp.Diagnostics.AddError("Error listing account users", err.Error())
+		}
+	} else {
+		w, diags := d.Client.GetWorkspaceClient()
+		resp.Diagnostics.Append(diags...)
+		if resp.Diagnostics.HasError() {
+			return
+		}
+
+		users, err = w.Users.ListAll(ctx, iam.ListUsersRequest{Filter: usersInfo.Filter.ValueString()})
+		if err != nil {
+			resp.Diagnostics.AddError("Error listing workspace users", err.Error())
+		}
+	}
+
+	for _, user := range users {
+		var tfUser iam_tf.User
+		resp.Diagnostics.Append(converters.GoSdkToTfSdkStruct(ctx, user, &tfUser)...)
+		if resp.Diagnostics.HasError() {
+			return
+		}
+		usersInfo.Users = append(usersInfo.Users, tfUser)
+	}
+
+	resp.Diagnostics.Append(resp.State.Set(ctx, usersInfo)...)
+}

internal/providers/pluginfw/products/user/data_users_acc_test.go

@@ -0,0 +1,124 @@
+package user_test
+
+import (
+	"testing"
+
+	"github.com/databricks/terraform-provider-databricks/internal/acceptance"
+	"github.com/hashicorp/terraform-plugin-testing/terraform"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+const dataSourceTemplate = `
+	resource "databricks_user" "user1" {
+		user_name = "tf-{var.STICKY_RANDOM}[email protected]"
+	}
+
+	resource "databricks_user" "user2" {
+		user_name = "tf-{var.STICKY_RANDOM}[email protected]"
+	}
+
+	data "databricks_users" "this" {
+		filter = "userName co \"testuser\""
+		depends_on = [databricks_user.user1, databricks_user.user2]
+	}
+`
+
+const dataSourceTemplateExtraAttributes = `
+	resource "databricks_group" "admins" {
+		display_name = "admins-{var.STICKY_RANDOM}"
+	}
+
+	resource "databricks_user" "user1" {
+		user_name = "tf-{var.STICKY_RANDOM}[email protected]"
+	}
+
+	resource "databricks_group_member" "membership" {
+		group_id = databricks_group.admins.id
+		member_id = databricks_user.user1.id
+	}
+
+	data "databricks_users" "this" {
+		filter = "userName eq \"me-{var.STICKY_RANDOM}@example.com\""
+		extra_attributes = "groups"
+		depends_on = [databricks_group_member.membership]
+	}
+`
+
+func checkUsersDataSourcePopulated(t *testing.T) func(s *terraform.State) error {
+	return func(s *terraform.State) error {
+		ds, ok := s.Modules[0].Resources["data.databricks_users.this"]
+		require.True(t, ok, "data.databricks_users.this has to be there")
+
+		usersCount := ds.Primary.Attributes["users.#"]
+		require.Equal(t, "2", usersCount, "expected two users")
+
+		userIds := []string{
+			ds.Primary.Attributes["users.0.id"],
+			ds.Primary.Attributes["users.1.id"],
+		}
+
+		expectedUserIDs := []string{
+			s.Modules[0].Resources["databricks_user.user1"].Primary.ID,
+			s.Modules[0].Resources["databricks_user.user2"].Primary.ID,
+		}
+
+		assert.ElementsMatch(t, expectedUserIDs, userIds, "expected user ids to match")
+
+		return nil
+	}
+}
+
+func checkUsersDataSourceWithGroups(t *testing.T) func(s *terraform.State) error {
+	return func(s *terraform.State) error {
+		ds, ok := s.Modules[0].Resources["data.databricks_users.this"]
+		require.True(t, ok, "data.databricks_users.this must be present")
+
+		usersCount := ds.Primary.Attributes["users.#"]
+		require.Equal(t, "1", usersCount, "expected one user")
+
+		userPrefix := "users.0."
+
+		groupsCountAttr := userPrefix + "groups.#"
+		groupsCount, exists := ds.Primary.Attributes[groupsCountAttr]
+		require.True(t, exists, "attribute groups.# should be present")
+		require.Equal(t, "1", groupsCount, "expected one group membership")
+
+		groupIdAttr := userPrefix + "groups.0.value"
+		groupId, exists := ds.Primary.Attributes[groupIdAttr]
+		require.True(t, exists, "attribute group.0.value should be present")
+
+		expectedGroupId := s.Modules[0].Resources["databricks_group.admins"].Primary.ID
+		assert.Equal(t, expectedGroupId, groupId, "group id should match the admins group id")
+
+		return nil
+	}
+}
+
+func TestAccDataSourceDataUsers(t *testing.T) {
+	acceptance.AccountLevel(t, acceptance.Step{
+		Template: dataSourceTemplate,
+		Check:    checkUsersDataSourcePopulated(t),
+	})
+}
+
+func TestWorkspaceDataSourceDataUsers(t *testing.T) {
+	acceptance.WorkspaceLevel(t, acceptance.Step{
+		Template: dataSourceTemplate,
+		Check:    checkUsersDataSourcePopulated(t),
+	})
+}
+
+func TestAccDataSourceUsers_WithGroups(t *testing.T) {
+	acceptance.AccountLevel(t, acceptance.Step{
+		Template: dataSourceTemplateExtraAttributes,
+		Check:    checkUsersDataSourceWithGroups(t),
+	})
+}
+
+func TestWorkspaceDataSourceUsers_WithGroups(t *testing.T) {
+	acceptance.WorkspaceLevel(t, acceptance.Step{
+		Template: dataSourceTemplateExtraAttributes,
+		Check:    checkUsersDataSourceWithGroups(t),
+	})
+}