Update to latest Unity Catalog privileges model (#1556)

Author: nkvuong

catalog/resource_grants.go

@@ -188,9 +188,10 @@ var mapping = securableMapping{
 		"CREATE_MATERIALIZED_VIEW": true,
 	},
 	"storage_credential": {
-		"CREATE_TABLE": true,
-		"READ_FILES":   true,
-		"WRITE_FILES":  true,
+		"CREATE_TABLE":             true,
+		"READ_FILES":               true,
+		"WRITE_FILES":              true,
+		"CREATE_EXTERNAL_LOCATION": true,
 
 		// v1.0
 		"ALL_PRIVILEGES":        true,
@@ -214,6 +215,9 @@ var mapping = securableMapping{
 		"CREATE_RECIPIENT":          true,
 		"CREATE_PROVIDER":           true,
 	},
+	"function": {
+		"EXECUTE": true,
+	},
 }
 
 func setToStrings(set *schema.Set) (ss []string) {

docs/resources/cluster.md

@@ -225,7 +225,7 @@ Example of pushing all cluster logs to S3:
 ```hcl
 cluster_log_conf {
   s3 {
-    destination = "s3a://acmecorp-main/cluster-logs"
+    destination = "s3://acmecorp-main/cluster-logs"
     region      = "us-east-1"
   }
 }
@@ -260,7 +260,7 @@ Example of taking init script from S3:
 ```hcl
 init_scripts {
   s3 {
-    destination = "s3a://acmecorp-main/init-scripts/install-elk.sh"
+    destination = "s3://acmecorp-main/init-scripts/install-elk.sh"
     region      = "us-east-1"
   }
 }

docs/resources/grants.md

@@ -3,20 +3,32 @@ subcategory: "Unity Catalog"
 ---
 # databricks_grants Resource
 
--> **Public Preview** This feature is in [Public Preview](https://docs.databricks.com/release-notes/release-types.html). Contact your Databricks representative to request access. 
+-> **Public Preview** This feature is in [Public Preview](https://docs.databricks.com/release-notes/release-types.html). Contact your Databricks representative to request access.
 
 In Unity Catalog all users initially have no access to data. Only Metastore Admins can create objects and can grant/revoke access on individual objects to users and groups. Every securable object in Unity Catalog has an owner. The owner can be any account-level user or group, called principals in general. The principal that creates an object becomes its owner. Owners receive all privileges on the securable object (e.g., `SELECT` and `MODIFY` on a table), as well as the permission to grant privileges to other principals.
 
 Unity Catalog supports the following privileges on securable objects:
-* `SELECT` - Allows the grantee to read data from the securable (applicable to tables and views).
-* `MODIFY` - Allows the grantee to add, update and delete data to or from the securable. (applicable to tables)
-* `CREATE` - Allows the grantee to create child objects within this securable.
-* `USAGE` - This privilege does not grant access to the securable itself, but allows the grantee to traverse the securable in order to access its child objects. For example, to select data from a table, users need to have the `SELECT` privilege on that table and `USAGE` privileges on its parent schema and parent catalog. Thus, you can use this privilege to restrict access to sections of your data namespace to specific groups.
+
+- `USAGE`: Applicable object types: `CATALOG`, `SCHEMA`. This privilege does not grant access to the securable itself, but is needed for a user to interact with any object within the securable. For example, to select data from a table, users need to have the `SELECT` privilege on that table and `USAGE` privileges on its parent schema and parent catalog.
+  
+  This is useful for allowing schema and catalog owners to be able to limit how far individual table owners can share data they produce. A table owner granting `SELECT` to another user does not allow that user read access to the table unless they also have `USAGE` on the schema and catalog.
+- `SELECT`: Applicable object types: `TABLE`, `VIEW`. Allows a user to select from a table or view, if the user also has `USAGE` on its parent catalog and schema.
+- `MODIFY`: Applicable object types: `TABLE`. Allows a user to add, update, and delete data to or from the table if the user also has `USAGE` on its parent catalog and schema.
+- `CREATE`: Applicable object types: `CATALOG`, `SCHEMA`. If applied to a catalog, allows a user to create a schema. The user also requires the `USAGE` permission on the catalog.
+
+  If applied to a schema, allows a user to create a table or view in the schema. The user also requires the `USAGE` permission on its parent catalog and the schema.
+- `EXECUTE`: Applicable object types: `FUNCTION`. Allows a user to invoke a user defined function, if the user also has `USAGE` on its parent catalog and schema.
+- `CREATE_TABLE`: Applicable object types: `EXTERNAL_LOCATION`, `STORAGE_CREDENTIAL`. Allows a user to create external tables directly in your cloud tenant using an external location or storage credential. Databricks recommends granting this privilege on an external location rather than storage credential; because the privilege is scoped to a path, it allows more control over where users can create external tables in your cloud tenant.
+- `READ_FILES`: Applicable object types: `EXTERNAL_LOCATION`, `STORAGE_CREDENTIAL`. Allows a user to read files directly from your cloud tenant (for example from S3 or ADLS). Databricks recommends granting this privilege on an external location rather than storage credential; because the privilege is scoped to a path it allows more control over from where users can read data.
+- `WRITE_FILES`: Applicable object types: `EXTERNAL_LOCATION`, `STORAGE_CREDENTIAL`. Allows a user to write files directly into your cloud tenant (for example into S3 or ADLS). We recommend granting this privilege on an external location rather than storage credential (since it is scoped to a path it allows more control over where users can write data to).
+- `ALL_PRIVILEGES`: Applicable object types: All object types. Allows a user to grant or revoke all privileges applicable to the securable without explicitly specifying them. This expands to all available privileges at the time of the grant.
+
+In Unity Catalog, privileges are not inherited on child securable objects. For example, if you grant the `CREATE` privilege on a catalog to a user, the user does not automatically have the `CREATE` privilege on all schemas in the catalog.
 
 Every `databricks_grants` resource must have exactly one securable identifier and one or more `grant` blocks with the following arguments:
 
-* `principal` - User or group name.
-* `privileges` - One or more privileges that are specific to a securable type.
+- `principal` - User or group name.
+- `privileges` - One or more privileges that are specific to a securable type.
 
 Terraform will handle any configuration drift on every `terraform apply` run, even when grants are changed outside of Terraform state.
 
@@ -51,13 +63,13 @@ resource "databricks_grants" "sandbox" {
 
 ## Schema grants
 
-You can grant `CREATE` and `USAGE` privileges to [*`catalog`*.*`database`*](schema.md) specified in the `schema` attribute:
+You can grant `CREATE` and `USAGE` privileges to [*`catalog`*.*`schema`*](schema.md) specified in the `schema` attribute:
 
 ```hcl
 resource "databricks_schema" "things" {
   catalog_name = databricks_catalog.sandbox.id
   name         = "things"
-  comment      = "this database is managed by terraform"
+  comment      = "this schema is managed by terraform"
   properties = {
     kind = "various"
   }
@@ -74,7 +86,7 @@ resource "databricks_grants" "things" {
 
 ## Table grants
 
-You can grant `MODIFY` and `SELECT` privileges to [*`catalog`*.*`database`*.*`table`*](table.md) specified in the `table` attribute. You can define a table through [databricks_table](table.md) resource.
+You can grant `MODIFY` and `SELECT` privileges to [*`catalog`*.*`schema`*.*`table`*](table.md) specified in the `table` attribute. You can define a table through [databricks_table](table.md) resource.
 
 ```hcl
 resource "databricks_grants" "customers" {
@@ -112,11 +124,11 @@ resource "databricks_grants" "things" {
 
 ## View grants
 
-You can grant `SELECT` privileges to [*`catalog`*.*`database`*.*`view`*](table.md) specified in `view` attribute. You can define a view through [databricks_table](table.md) resource.
+You can grant `SELECT` privileges to [*`catalog`*.*`schema`*.*`view`*](table.md) specified in `table` attribute. You can define a view through [databricks_table](table.md) resource.
 
 ```hcl
 resource "databricks_grants" "customer360" {
-  view = "main.reporting.customer360"
+  table = "main.reporting.customer360"
   grant {
     principal  = "Data Analysts"
     privileges = ["SELECT"]
@@ -135,7 +147,7 @@ data "databricks_views" "customers" {
 resource "databricks_grants" "customers" {
   for_each = data.databricks_views.customers.ids
 
-  view = each.value
+  table = each.value
 
   grant {
     principal  = "sensitive"
@@ -146,7 +158,7 @@ resource "databricks_grants" "customers" {
 
 ## Storage credential grants
 
-You can grant `CREATE_TABLE`, `READ_FILES`, and `WRITE_FILES` privileges to [databricks_storage_credential](storage_credential.md) id specified in `storage_credential` attribute:
+You can grant `CREATE_TABLE`, `READ_FILES`, `WRITE_FILES` and `CREATE_EXTERNAL_LOCATION` privileges to [databricks_storage_credential](storage_credential.md) id specified in `storage_credential` attribute:
 
 ```hcl
 resource "databricks_storage_credential" "external" {