[Feature] Add datasource databricks_users

docs/data-sources/users.md

@@ -0,0 +1,73 @@
+---
+subcategory: "Security"
+---
+
+# databricks_users Data Source
+
+-> **Note** 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" {
+  user_name_contains = "@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: 
+
+- `display_name_contains` - (Optional) A substring to filter users by their display name. Only users whose display names contain this substring will be included in the results.
+- `user_name_contains` - (Optional) A substring to filter users by their username. Only users whose usernames contain this substring will be included in the results.
+
+->**Note** You can specify **exactly one** of `display_name_contains` or `user_name_contains`. If neither is specified, all users will be returned.
+
+## 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. 
+    - `roles` - Indicates if the user has the admin role.
+      - `$ref`
+      - `value`
+      - `display`
+      - `primary`
+      - `type`
+    - `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.go

@@ -23,6 +23,7 @@ import (
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/resources/qualitymonitor"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/resources/registered_model"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/resources/sharing"
+	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/resources/user"
 	"github.com/databricks/terraform-provider-databricks/internal/providers/pluginfw/resources/volume"
 
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
@@ -62,6 +63,7 @@ func (p *DatabricksProviderPluginFramework) DataSources(ctx context.Context) []f
 		sharing.DataSourceShare,
 		sharing.DataSourceShares,
 		catalog.DataSourceFunctions,
+		user.DataSourceUsers,
 	}
 }
 

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

@@ -0,0 +1,113 @@
+package user
+
+import (
+	"context"
+	"fmt"
+
+	"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/tfschema"
+	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+)
+
+func DataSourceUsers() datasource.DataSource {
+	return &UsersDataSource{}
+}
+
+var _ datasource.DataSourceWithConfigure = &UsersDataSource{}
+
+type UsersDataSource struct {
+	Client *common.DatabricksClient
+}
+
+type UsersInfo struct {
+	DisplayNameContains string     `json:"display_name_contains,omitempty" tf:"computed"`
+	UserNameContains    string     `json:"user_name_contains,omitempty" tf:"computed"`
+	Users               []iam.User `json:"users,omitempty" tf:"computed"`
+}
+
+func (d *UsersDataSource) Metadata(ctx context.Context, req datasource.MetadataRequest, resp *datasource.MetadataResponse) {
+	resp.TypeName = "databricks_users"
+}
+
+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)
+	}
+}
+
+// AppendDiagAndCheckErrors is a helper function that simplifies error handling by combining the appending of diagnostics and the checking of errors in a single step.
+// It is particularly useful in data source and resource read operations where you want to append diagnostics and immediately determine if an error has occurred.
+func AppendDiagAndCheckErrors(resp *datasource.ReadResponse, diags diag.Diagnostics) bool {
+	resp.Diagnostics.Append(diags...)
+	return resp.Diagnostics.HasError()
+}
+
+// DiagsFromError helps us create an error diagnostic from an error.
+func DiagsFromError(summary string, err error) diag.Diagnostics {
+	return diag.Diagnostics{
+		diag.NewErrorDiagnostic(summary, err.Error()),
+	}
+}
+
+func validateFilters(data *UsersInfo) diag.Diagnostics {
+	if data.DisplayNameContains != "" && data.UserNameContains != "" {
+		return diag.Diagnostics{diag.NewErrorDiagnostic("Invalid configuration", "Exactly one of display_name_contains or user_name_contains should be specified, not both.")}
+	}
+	return nil
+}
+
+func (d *UsersDataSource) Read(ctx context.Context, req datasource.ReadRequest, resp *datasource.ReadResponse) {
+	var userInfo UsersInfo
+
+	diags := req.Config.Get(ctx, &userInfo)
+	diags = append(diags, validateFilters(&userInfo)...)
+	if AppendDiagAndCheckErrors(resp, diags) {
+		return
+	}
+
+	var filter string
+
+	if userInfo.DisplayNameContains != "" {
+		filter = fmt.Sprintf("displayName co \"%s\"", userInfo.DisplayNameContains)
+	} else if userInfo.UserNameContains != "" {
+		filter = fmt.Sprintf("userName co \"%s\"", userInfo.UserNameContains)
+	}
+
+	var users []iam.User
+	var err error
+
+	if d.Client.Config.IsAccountClient() {
+		a, diags := d.Client.GetAccountClient()
+		if AppendDiagAndCheckErrors(resp, diags) {
+			return
+		}
+		users, err = a.Users.ListAll(ctx, iam.ListAccountUsersRequest{Filter: filter})
+		if err != nil && AppendDiagAndCheckErrors(resp, DiagsFromError("Error listing account users", err)) {
+			return
+		}
+	} else {
+		w, diags := d.Client.GetWorkspaceClient()
+		if AppendDiagAndCheckErrors(resp, diags) {
+			return
+		}
+		users, err = w.Users.ListAll(ctx, iam.ListUsersRequest{Filter: filter})
+		if err != nil && AppendDiagAndCheckErrors(resp, DiagsFromError("Error listing workspace users", err)) {
+			return
+		}
+	}
+
+	userInfo.Users = users
+	resp.Diagnostics.Append(resp.State.Set(ctx, userInfo)...)
+}

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

@@ -0,0 +1,62 @@
+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 = "[email protected]"
+	}
+
+	resource "databricks_user" "user2" {
+		user_name = "[email protected]"
+	}
+
+	data "databricks_users" "this" {
+		user_name_contains = "testuser"
+	}
+`
+
+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 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),
+	})
+}

internal/providers/pluginfw/resources/user/data_users_test.go

@@ -0,0 +1,19 @@
+package user
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestValidateFilters(t *testing.T) {
+	userInfo := UsersInfo{
+		DisplayNameContains: "filter",
+		UserNameContains:    "another_filter",
+	}
+	actualDiagnostics := validateFilters(&userInfo)
+	expectedDiagnostics := diag.Diagnostics{diag.NewErrorDiagnostic("Invalid configuration", "Exactly one of display_name_contains or user_name_contains should be specified, not both.")}
+	assert.True(t, actualDiagnostics.HasError())
+	assert.Equal(t, expectedDiagnostics, actualDiagnostics)
+}