Update documentation for Delta Sharing resources; refactoring relevant resources & data sources (#3466)

nkvuong · web-flow · commit e10d36c7b196 · 2024-04-16T08:34:56.000Z
* moving delta sharing resources to sharing namepsace

* docs
diff --git a/docs/data-sources/share.md b/docs/data-sources/share.md
@@ -1,5 +1,5 @@
 ---
-subcategory: "Unity Catalog"
+subcategory: "Delta Sharing"
 ---
 # databricks_share Data Source
 
diff --git a/docs/data-sources/shares.md b/docs/data-sources/shares.md
@@ -1,5 +1,5 @@
 ---
-subcategory: "Unity Catalog"
+subcategory: "Delta Sharing"
 ---
 # databricks_shares Data Source
 
diff --git a/docs/resources/provider.md b/docs/resources/provider.md
@@ -1,11 +1,11 @@
 ---
-subcategory: "Unity Catalog"
+subcategory: "Delta Sharing"
 ---
 # databricks_provider Resource
 
 -> **Note** This resource could be only used with workspace-level provider!
 
-Within a metastore, Unity Catalog provides the ability to create a provider which contains a list of shares that have been shared with you.
+In Delta Sharing, a provider is an entity that shares data with a recipient. Within a metastore, Unity Catalog provides the ability to create a provider which contains a list of shares that have been shared with you.
 
 A `databricks_provider` is contained within [databricks_metastore](metastore.md) and can contain a list of shares that have been shared with you.
 
diff --git a/docs/resources/recipient.md b/docs/resources/recipient.md
@@ -1,11 +1,13 @@
 ---
-subcategory: "Unity Catalog"
+subcategory: "Delta Sharing"
 ---
 # databricks_recipient Resource
 
 -> **Note** This resource could be only used with workspace-level provider!
 
-Within a metastore, Unity Catalog provides the ability to create a recipient to attach delta shares to.
+In Delta Sharing, a recipient is an entity that receives shares from a provider. In Unity Catalog, a share is a securable object that represents an organization and associates it with a credential or secure sharing identifier that allows that organization to access one or more shares.
+
+As a data provider (sharer), you can define multiple recipients for any given Unity Catalog metastore, but if you want to share data from multiple metastores with a particular user or group of users, you must define the recipient separately for each metastore. A recipient can have access to multiple shares.
 
 A `databricks_recipient` is contained within [databricks_metastore](metastore.md) and can have permissions to `SELECT` from a list of shares.
 
@@ -113,7 +115,6 @@ In addition to all arguments above, the following attributes are exported:
 * `cloud` - Cloud vendor of the recipient's Unity Catalog Metstore. This field is only present when the authentication_type is `DATABRICKS`.
 * `region` - Cloud region of the recipient's Unity Catalog Metstore. This field is only present when the authentication_type is `DATABRICKS`.
 
-
 ## Related Resources
 
 The following resources are often used in the same context:
diff --git a/docs/resources/share.md b/docs/resources/share.md
@@ -1,13 +1,13 @@
 ---
-subcategory: "Unity Catalog"
+subcategory: "Delta Sharing"
 ---
 # databricks_share Resource
 
 -> **Note** This resource could be only used with workspace-level provider!
 
-Within a metastore, Unity Catalog provides the ability to create a share, which is a named object that contains a collection of tables in a metastore that you want to share as a group. A share can contain tables from only a single metastore. You can add or remove tables from a share at any time.
+In Delta Sharing, a share is a read-only collection of tables and table partitions that a provider wants to share with one or more recipients. If your recipient uses a Unity Catalog-enabled Databricks workspace, you can also include notebook files, views (including dynamic views that restrict access at the row and column level), Unity Catalog volumes, and Unity Catalog models in a share.
 
-A `databricks_share` is contained within [databricks_metastore](metastore.md) and can contain a list of tables.
+In a Unity Catalog-enabled Databricks workspace, a share is a securable object registered in Unity Catalog. A `databricks_share` is contained within a [databricks_metastore](metastore.md). If you remove a share from your Unity Catalog metastore, all recipients of that share lose the ability to access it.
 
 ## Example Usage
 
diff --git a/exporter/importables.go b/exporter/importables.go
@@ -29,6 +29,7 @@ import (
 	"github.com/databricks/terraform-provider-databricks/permissions"
 	"github.com/databricks/terraform-provider-databricks/pipelines"
 	"github.com/databricks/terraform-provider-databricks/repos"
+	tfsharing "github.com/databricks/terraform-provider-databricks/sharing"
 	tfsql "github.com/databricks/terraform-provider-databricks/sql"
 	sql_api "github.com/databricks/terraform-provider-databricks/sql/api"
 	"github.com/databricks/terraform-provider-databricks/storage"
@@ -2730,7 +2731,7 @@ var resourcesMap map[string]importable = map[string]importable{
 		},
 		Import: func(ic *importContext, r *resource) error {
 			// TODO: do we need to emit the owner See comment for the owner...
-			var share tfcatalog.ShareInfo
+			var share tfsharing.ShareInfo
 			s := ic.Resources["databricks_share"].Schema
 			common.DataToStructPointer(r.Data, s, &share)
 			// TODO: how to link recipients to share?
diff --git a/exporter/importables_test.go b/exporter/importables_test.go
@@ -31,6 +31,7 @@ import (
 	"github.com/databricks/terraform-provider-databricks/repos"
 	"github.com/databricks/terraform-provider-databricks/scim"
 	"github.com/databricks/terraform-provider-databricks/secrets"
+	tfsharing "github.com/databricks/terraform-provider-databricks/sharing"
 	"github.com/databricks/terraform-provider-databricks/storage"
 	"github.com/databricks/terraform-provider-databricks/workspace"
 	"github.com/hashicorp/hcl/v2/hclwrite"
@@ -1771,11 +1772,11 @@ func TestImportSchema(t *testing.T) {
 func TestImportShare(t *testing.T) {
 	ic := importContextForTest()
 	ic.enableServices("uc-grants,uc-volumes,uc-models,uc-tables")
-	d := tfcatalog.ResourceShare().ToResource().TestResourceData()
-	scm := tfcatalog.ResourceShare().Schema
-	share := tfcatalog.ShareInfo{
+	d := tfsharing.ResourceShare().ToResource().TestResourceData()
+	scm := tfsharing.ResourceShare().Schema
+	share := tfsharing.ShareInfo{
 		Name: "stest",
-		Objects: []tfcatalog.SharedDataObject{
+		Objects: []tfsharing.SharedDataObject{
 			{
 				DataObjectType: "TABLE",
 				Name:           "ctest.stest.table1",
diff --git a/provider/provider.go b/provider/provider.go
@@ -84,8 +84,8 @@ func DatabricksProvider() *schema.Provider {
 			"databricks_schemas":                  catalog.DataSourceSchemas().ToResource(),
 			"databricks_service_principal":        scim.DataSourceServicePrincipal().ToResource(),
 			"databricks_service_principals":       scim.DataSourceServicePrincipals().ToResource(),
-			"databricks_share":                    catalog.DataSourceShare().ToResource(),
-			"databricks_shares":                   catalog.DataSourceShares().ToResource(),
+			"databricks_share":                    sharing.DataSourceShare().ToResource(),
+			"databricks_shares":                   sharing.DataSourceShares().ToResource(),
 			"databricks_spark_version":            clusters.DataSourceSparkVersion().ToResource(),
 			"databricks_sql_warehouse":            sql.DataSourceWarehouse().ToResource(),
 			"databricks_sql_warehouses":           sql.DataSourceWarehouses().ToResource(),
@@ -151,7 +151,7 @@ func DatabricksProvider() *schema.Provider {
 			"databricks_permission_assignment":       access.ResourcePermissionAssignment().ToResource(),
 			"databricks_permissions":                 permissions.ResourcePermissions().ToResource(),
 			"databricks_pipeline":                    pipelines.ResourcePipeline().ToResource(),
-			"databricks_provider":                    catalog.ResourceProvider().ToResource(),
+			"databricks_provider":                    sharing.ResourceProvider().ToResource(),
 			"databricks_recipient":                   sharing.ResourceRecipient().ToResource(),
 			"databricks_registered_model":            catalog.ResourceRegisteredModel().ToResource(),
 			"databricks_repo":                        repos.ResourceRepo().ToResource(),
@@ -162,7 +162,7 @@ func DatabricksProvider() *schema.Provider {
 			"databricks_service_principal":           scim.ResourceServicePrincipal().ToResource(),
 			"databricks_service_principal_role":      aws.ResourceServicePrincipalRole().ToResource(),
 			"databricks_service_principal_secret":    tokens.ResourceServicePrincipalSecret().ToResource(),
-			"databricks_share":                       catalog.ResourceShare().ToResource(),
+			"databricks_share":                       sharing.ResourceShare().ToResource(),
 			"databricks_sql_dashboard":               sql.ResourceSqlDashboard().ToResource(),
 			"databricks_sql_endpoint":                sql.ResourceSqlEndpoint().ToResource(),
 			"databricks_sql_global_config":           sql.ResourceSqlGlobalConfig().ToResource(),
diff --git a/sharing/data_share.go b/sharing/data_share.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"context"
diff --git a/sharing/data_share_test.go b/sharing/data_share_test.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"testing"
diff --git a/sharing/data_shares.go b/sharing/data_shares.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"context"
diff --git a/sharing/data_shares_test.go b/sharing/data_shares_test.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"testing"
diff --git a/sharing/resource_provider.go b/sharing/resource_provider.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"context"
diff --git a/sharing/resource_provider_test.go b/sharing/resource_provider_test.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"testing"
diff --git a/sharing/resource_share.go b/sharing/resource_share.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"context"
diff --git a/sharing/resource_share_test.go b/sharing/resource_share_test.go
@@ -1,4 +1,4 @@
-package catalog
+package sharing
 
 import (
 	"testing"

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package catalog`
	`1`	`+package sharing`
`2`	`2`
`3`	`3`	`import (`
`4`	`4`	`"context"`