Skip to content

Commit

Permalink
Update docs for databricks_grants with new permissions model (#1657)
Browse files Browse the repository at this point in the history
  • Loading branch information
@nkvuong
nkvuong committed Oct 7, 2022
1 parent b5e6834 commit d0fecab
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 35 deletions.
27 changes: 23 additions & 4 deletions catalog/resource_grants.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -171,9 +171,18 @@ var mapping = securableMapping{
"USAGE": true,

// v1.0
"ALL_PRIVILEGES": true,
"USE_CATALOG": true,
"CREATE_SCHEMA": true,
"ALL_PRIVILEGES": true,
"USE_CATALOG": true,
"USE_SCHEMA": true,
"CREATE_SCHEMA": true,
"CREATE_TABLE": true,
"CREATE_VIEW": true,
"CREATE_FUNCTION": true,
"CREATE_MATERIALIZED_VIEW": true,
"EXECUTE": true,
"MODIFY": true,
"SELECT": true,
"REFRESH": true,
},
"schema": {
"CREATE": true,
Expand All @@ -186,6 +195,10 @@ var mapping = securableMapping{
"CREATE_VIEW": true,
"CREATE_FUNCTION": true,
"CREATE_MATERIALIZED_VIEW": true,
"EXECUTE": true,
"MODIFY": true,
"SELECT": true,
"REFRESH": true,
},
"storage_credential": {
"CREATE_TABLE": true,
Expand Down Expand Up @@ -216,7 +229,13 @@ var mapping = securableMapping{
"CREATE_PROVIDER": true,
},
"function": {
"EXECUTE": true,
"ALL_PRIVILEGES": true,
"EXECUTE": true,
},
"materialized_view": {
"ALL_PRIVILEGES": true,
"SELECT": true,
"REFRESH": true,
},
}

Expand Down
2 changes: 1 addition & 1 deletion docs/guides/unity-catalog.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,7 @@ resource "databricks_metastore_assignment" "default_metastore" {
provider = databricks.workspace
for_each = toset(var.databricks_workspace_ids)
workspace_id = each.key
metastore_id = databricks_metastore.unity.id
metastore_id = databricks_metastore.this.id
default_catalog_name = "hive_metastore"
}
```
Expand Down
77 changes: 47 additions & 30 deletions docs/resources/grants.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,38 +3,55 @@ subcategory: "Unity Catalog"
---
# databricks_grants Resource

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.
-> **Note**
This article refers to the privileges and inheritance model in Privilege Model version 1.0. If you created your metastore during the public preview (before August 25, 2022), you can upgrade to Privilege Model version 1.0 following [Upgrade to privilege inheritance](https://docs.databricks.com/data-governance/unity-catalog/hive-metastore.html)

Unity Catalog supports the following privileges on securable objects:
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.

- `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.
Securable objects are hierarchical and privileges are inherited downward. The highest level object that privileges are inherited from is the catalog. This means that granting a privilege on a catalog or schema automatically grants the privilege to all current and future objects within the catalog or schema. Privileges that are granted on a metastore are not inherited.

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.

The securable objects are:

- `METATORE`: The top-level container for metadata. Each metastore exposes a three-level namespace (`catalog`.`schema`.`table`) that organizes your data.
- `CATALOG`: The first layer of the object hierarchy, used to organize your data assets.
- `SCHEMA`: Also known as databases, schemas are the second layer of the object hierarchy and contain tables and views.
- `TABLE`: The lowest level in the object hierarchy, tables can be _external_ (stored in external locations in your cloud storage of choice) or _managed_ tables (stored in a storage container in your cloud storage that you create expressly for UC).
- `VIEW`: A read-only object created from one or more tables that is contained within a schema.
- `EXTERNAL LOCATION`: An object that contains a reference to a storage credential and a cloud storage path that is contained within a metatore.
- `STORAGE CREDENTIAL`: An object that encapsulates a long-term cloud credential that provides access to cloud storage that is contained within a metatore.

Terraform will handle any configuration drift on every `terraform apply` run, even when grants are changed outside of Terraform state.

It is required to define all permissions for a securable in a single resource, otherwise Terraform cannot guarantee config drift prevention.

Below summarizes which privilege types apply to each securable object in the catalog:

## Metastore grants

You can grant `CREATE_CATALOG`, `CREATE_EXTERNAL_LOCATION`, `CREATE_SHARE`, `CREATE_RECIPIENT` and `CREATE_PROVIDER` privileges to [databricks_metastore](metastore.md) id specified in `metastore` attribute.

```hcl
resource "databricks_grants" "sandbox" {
metastore = databricks_metastore.this.id
grant {
principal = "Data Engineers"
privileges = ["CREATE_CATALOG", "CREATE_EXTERNAL_LOCATION"]
}
grant {
principal = "Data Sharer"
privileges = ["CREATE_RECIPIENT", "CREATE_SHARE"]
}
}
```

## Catalog grants

You can grant `CREATE` and `USAGE` privileges to [databricks_catalog](catalog.md) specified in the `catalog` attribute:
You can grant `ALL_PRIVILEGES`, `CREATE_SCHEMA`, `USE_CATALOG` privileges to [databricks_catalog](catalog.md) specified in the `catalog` attribute. You can also grant `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VIEW`, `EXECUTE`, `MODIFY`, `SELECT` and `USE_SCHEMA` at the catalog level to apply them to the pertinent current and future securable objects within the catalog:

```hcl
resource "databricks_catalog" "sandbox" {
Expand All @@ -50,18 +67,22 @@ resource "databricks_grants" "sandbox" {
catalog = databricks_catalog.sandbox.name
grant {
principal = "Data Scientists"
privileges = ["USAGE", "CREATE"]
privileges = ["USE_CATALOG", "USE_SCHEMA", "CREATE_TABLE", "SELECT"]
}
grant {
principal = "Data Engineers"
privileges = ["USAGE"]
privileges = ["USE_CATALOG", "USE_SCHEMA", "CREATE_SCHEMA", "CREATE_TABLE", "MODIFY"]
}
grant {
principal = "Data Analyst"
privileges = ["USE_CATALOG", "USE_SCHEMA", "SELECT"]
}
}
```

## Schema grants

You can grant `CREATE` and `USAGE` privileges to [*`catalog`*.*`schema`*](schema.md) specified in the `schema` attribute:
You can grant `ALL_PRIVILEGES`, `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VIEW` and `USE_SCHEMA` privileges to [_`catalog.schema`_](schema.md) specified in the `schema` attribute. You can also grant `EXECUTE`, `MODIFY` and `SELECT` at the schema level to apply them to the pertinent current and future securable objects within the schema:

```hcl
resource "databricks_schema" "things" {
Expand All @@ -77,14 +98,14 @@ resource "databricks_grants" "things" {
schema = databricks_schema.things.id
grant {
principal = "Data Engineers"
privileges = ["USAGE"]
privileges = ["USE_SCHEMA", "MODIFY"]
}
}
```

## Table grants

You can grant `MODIFY` and `SELECT` privileges to [*`catalog`*.*`schema`*.*`table`*](tables.md) specified in the `table` attribute.
You can grant `ALL_PRIVILEGES`, `SELECT` and `MODIFY` privileges to [_`catalog.schema.table`_](tables.md) specified in the `table` attribute.

```hcl
resource "databricks_grants" "customers" {
Expand Down Expand Up @@ -122,7 +143,7 @@ resource "databricks_grants" "things" {

## View grants

You can grant `SELECT` privileges to [*`catalog`*.*`schema`*.*`view`*](views.md) specified in `table` attribute.
You can grant `ALL_PRIVILEGES` and `SELECT` privileges to [_`catalog.schema.view`_](views.md) specified in `table` attribute.

```hcl
resource "databricks_grants" "customer360" {
Expand Down Expand Up @@ -156,7 +177,7 @@ resource "databricks_grants" "customers" {

## Storage credential grants

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:
You can grant `ALL_PRIVILEGES`, `CREATE_EXTERNAL_TABLE`, `READ_FILES` and `WRITE_FILES` privileges to [databricks_storage_credential](storage_credential.md) id specified in `storage_credential` attribute:

```hcl
resource "databricks_storage_credential" "external" {
Expand All @@ -178,7 +199,7 @@ resource "databricks_grants" "external_creds" {

## Storage location grants

You can grant `CREATE_TABLE`, `READ_FILES`, and `WRITE_FILES` privileges to [databricks_external_location](external_location.md) id specified in `external_location` attribute:
You can grant `ALL_PRIVILEGES`, `CREATE_EXTERNAL_TABLE`, `READ_FILES` and `WRITE_FILES` privileges to [databricks_external_location](external_location.md) id specified in `external_location` attribute:

```hcl
resource "databricks_external_location" "some" {
Expand All @@ -197,10 +218,6 @@ resource "databricks_grants" "some" {
}
```

## Metastore grants

You can grant `CREATE_CATALOG`, `CREATE_EXTERNAL_LOCATION`, `CREATE_STORAGE_CREDENTIAL`, `CREATE_SHARE`, `CREATE_RECIPIENT`, and `CREATE_PROVIDER` privileges to [databricks_metastore](metastore.md) id specified in `metastore` attribute.

## Other access control

You can control Databricks General Permissions through [databricks_permissions](permissions.md) resource.

0 comments on commit d0fecab

Please sign in to comment.