Skip to content

grants.md

Latest commit

 

History

History
382 lines (305 loc) · 13.3 KB

grants.md

File metadata and controls

382 lines (305 loc) · 13.3 KB
Raw
subcategory Unity Catalog

databricks_grants Resource

API Documentation

-> 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

-> Most of Unity Catalog APIs are only accessible via workspace-level APIs. This design may change in the future. Account-level principal grants can be assigned with any valid workspace as the Unity Catalog is decoupled from specific workspaces. More information in the official documentation.

~> This resource is authoritative for grants on securables. Configuring this resource for a securable will OVERWRITE any existing grants and changes made outside of Terraform will be reset. Use databricks_grant for more granular grant management.

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.

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 name, group name or service principal application ID.
  • privileges - One or more privileges that are specific to a securable type.
  • provider_config - (Optional) Configure the provider for management through account provider. This block consists of the following fields:
    • workspace_id - (Required) Workspace ID which the resource belongs to. This workspace must be part of the account which the provider is configured with.

For the latest list of privilege types that apply to each securable object in Unity Catalog, please refer to the official documentation

When applying grants using an identity with MANAGE permission, their MANAGE permission must also be defined, otherwise Terraform will remove their permissions, leading to errors.

Unlike the SQL specification, all privileges to be written with underscore instead of space, e.g. CREATE_TABLE and not CREATE TABLE. Below summarizes which privilege types apply to each securable object in the catalog:

Metastore grants

You can grant CREATE_CATALOG, CREATE_CLEAN_ROOM, CREATE_CONNECTION, CREATE_EXTERNAL_LOCATION, CREATE_PROVIDER, CREATE_RECIPIENT, CREATE_SHARE, CREATE_SERVICE_CREDENTIAL, CREATE_STORAGE_CREDENTIAL, SET_SHARE_PERMISSION, USE_MARKETPLACE_ASSETS, USE_PROVIDER, USE_RECIPIENT, and USE_SHARE privileges to databricks_metastore assigned to the workspace.

resource "databricks_grants" "sandbox" {
  metastore = "metastore_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 ALL_PRIVILEGES, APPLY_TAG, CREATE_CONNECTION, CREATE_SCHEMA, MANAGE, and USE_CATALOG privileges to databricks_catalog specified in the catalog attribute. You can also grant CREATE_FUNCTION, CREATE_TABLE, CREATE_VOLUME, EXECUTE, MODIFY, REFRESH, SELECT, READ_VOLUME, WRITE_VOLUME and USE_SCHEMA at the catalog level to apply them to the pertinent current and future securable objects within the catalog:

resource "databricks_catalog" "sandbox" {
  name    = "sandbox"
  comment = "this catalog is managed by terraform"
  properties = {
    purpose = "testing"
  }
}

resource "databricks_grants" "sandbox" {
  catalog = databricks_catalog.sandbox.name
  grant {
    principal  = "Data Scientists"
    privileges = ["USE_CATALOG", "USE_SCHEMA", "CREATE_TABLE", "SELECT"]
  }
  grant {
    principal  = "Data Engineers"
    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 ALL_PRIVILEGES, APPLY_TAG, CREATE_FUNCTION, CREATE_TABLE, CREATE_VOLUME, MANAGE and USE_SCHEMA privileges to catalog.schema specified in the schema attribute. You can also grant EXECUTE, MODIFY, REFRESH, SELECT, READ_VOLUME, WRITE_VOLUME at the schema level to apply them to the pertinent current and future securable objects within the schema:

resource "databricks_schema" "things" {
  catalog_name = databricks_catalog.sandbox.id
  name         = "things"
  comment      = "this schema is managed by terraform"
  properties = {
    kind = "various"
  }
}

resource "databricks_grants" "things" {
  schema = databricks_schema.things.id
  grant {
    principal  = "Data Engineers"
    privileges = ["USE_SCHEMA", "MODIFY"]
  }
}

Table grants

You can grant ALL_PRIVILEGES, APPLY_TAG, MANAGE, SELECT and MODIFY privileges to catalog.schema.table specified in the table attribute.

resource "databricks_grants" "customers" {
  table = "main.reporting.customers"
  grant {
    principal  = "Data Engineers"
    privileges = ["MODIFY", "SELECT"]
  }
  grant {
    principal  = "Data Analysts"
    privileges = ["SELECT"]
  }
}

You can also apply grants dynamically with databricks_tables data resource:

data "databricks_tables" "things" {
  catalog_name = "sandbox"
  schema_name  = "things"
}

resource "databricks_grants" "things" {
  for_each = data.databricks_tables.things.ids

  table = each.value

  grant {
    principal  = "sensitive"
    privileges = ["SELECT", "MODIFY"]
  }
}

View grants

You can grant ALL_PRIVILEGES, APPLY_TAG, MANAGE and SELECT privileges to catalog.schema.view specified in table attribute.

resource "databricks_grants" "customer360" {
  table = "main.reporting.customer360"
  grant {
    principal  = "Data Analysts"
    privileges = ["SELECT"]
  }
}

You can also apply grants dynamically with databricks_views data resource:

data "databricks_views" "customers" {
  catalog_name = "main"
  schema_name  = "customers"
}

resource "databricks_grants" "customers" {
  for_each = data.databricks_views.customers.ids

  table = each.value

  grant {
    principal  = "sensitive"
    privileges = ["SELECT", "MODIFY"]
  }
}

Volume grants

You can grant ALL_PRIVILEGES, APPLY_TAG, MANAGE, READ_VOLUME and WRITE_VOLUME privileges to catalog.schema.volume specified in the volume attribute.

resource "databricks_volume" "this" {
  name             = "quickstart_volume"
  catalog_name     = databricks_catalog.sandbox.name
  schema_name      = databricks_schema.things.name
  volume_type      = "EXTERNAL"
  storage_location = databricks_external_location.some.url
  comment          = "this volume is managed by terraform"
}

resource "databricks_grants" "volume" {
  volume = databricks_volume.this.id
  grant {
    principal  = "Data Engineers"
    privileges = ["WRITE_VOLUME"]
  }
}

Registered model grants

You can grant ALL_PRIVILEGES, APPLY_TAG, EXECUTE, and MANAGE privileges to catalog.schema.model specified in the model attribute.

resource "databricks_grants" "customers" {
  model = "main.reporting.customer_model"
  grant {
    principal  = "Data Engineers"
    privileges = ["APPLY_TAG", "EXECUTE"]
  }
  grant {
    principal  = "Data Analysts"
    privileges = ["EXECUTE"]
  }
}

Function grants

You can grant ALL_PRIVILEGES, EXECUTE, and MANAGE privileges to catalog.schema.function specified in the function attribute.

resource "databricks_grants" "udf" {
  function = "main.reporting.udf"

  grant {
    principal  = "Data Engineers"
    privileges = ["EXECUTE"]
  }
  grant {
    principal  = "Data Analysts"
    privileges = ["EXECUTE"]
  }
}

Service credential grants

You can grant ALL_PRIVILEGES, ACCESS, CREATE_CONNECTION, and MANAGE privileges to databricks_credential id specified in credential attribute:

resource "databricks_credential" "external" {
  name = aws_iam_role.external_data_access.name
  aws_iam_role {
    role_arn = aws_iam_role.external_data_access.arn
  }
  purpose = "SERVICE"
  comment = "Managed by TF"
}

resource "databricks_grants" "external_creds" {
  credential = databricks_credential.external.id
  grant {
    principal  = "Data Engineers"
    privileges = ["CREATE_CONNECTION"]
  }
}

Storage credential grants

You can grant ALL_PRIVILEGES, CREATE_EXTERNAL_LOCATION, CREATE_EXTERNAL_TABLE, MANAGE, READ_FILES and WRITE_FILES privileges to databricks_storage_credential id specified in storage_credential attribute:

resource "databricks_storage_credential" "external" {
  name = aws_iam_role.external_data_access.name
  aws_iam_role {
    role_arn = aws_iam_role.external_data_access.arn
  }
  comment = "Managed by TF"
}

resource "databricks_grants" "external_creds" {
  storage_credential = databricks_storage_credential.external.id
  grant {
    principal  = "Data Engineers"
    privileges = ["CREATE_EXTERNAL_TABLE"]
  }
}

External location grants

You can grant ALL_PRIVILEGES, CREATE_EXTERNAL_TABLE, CREATE_MANAGED_STORAGE, CREATE EXTERNAL VOLUME, MANAGE, READ_FILES and WRITE_FILES privileges to databricks_external_location id specified in external_location attribute:

resource "databricks_external_location" "some" {
  name            = "external"
  url             = "s3://${aws_s3_bucket.external.id}/some"
  credential_name = databricks_storage_credential.external.id
  comment         = "Managed by TF"
}

resource "databricks_grants" "some" {
  external_location = databricks_external_location.some.id
  grant {
    principal  = "Data Engineers"
    privileges = ["CREATE_EXTERNAL_TABLE", "READ_FILES"]
  }
  grant {
    principal  = databricks_service_principal.my_sp.application_id
    privileges = ["CREATE_EXTERNAL_TABLE", "READ_FILES"]
  }
  grant {
    principal  = databricks_group.my_group.display_name
    privileges = ["CREATE_EXTERNAL_TABLE", "READ_FILES"]
  }
  grant {
    principal  = databricks_group.my_user.user_name
    privileges = ["CREATE_EXTERNAL_TABLE", "READ_FILES"]
  }
}

Connection grants

You can grant ALL_PRIVILEGES, MANAGE, USE_CONNECTION and CREATE_FOREIGN_CATALOG to databricks_connection specified in foreign_connection attribute:

resource "databricks_connection" "mysql" {
  name            = "mysql_connection"
  connection_type = "MYSQL"
  comment         = "this is a connection to mysql db"
  options = {
    host     = "test.mysql.database.azure.com"
    port     = "3306"
    user     = "user"
    password = "password"
  }
  properties = {
    purpose = "testing"
  }
}

resource "databricks_grants" "some" {
  foreign_connection = databricks_connection.mysql.name
  grant {
    principal  = "Data Engineers"
    privileges = ["CREATE_FOREIGN_CATALOG", "USE_CONNECTION"]
  }
}

Delta Sharing share grants

You can grant SELECT to databricks_recipient on databricks_share name specified in share attribute:

resource "databricks_share" "some" {
  name = "my_share"
}

resource "databricks_recipient" "some" {
  name = "my_recipient"
}

resource "databricks_grants" "some" {
  share = databricks_share.some.name
  grant {
    principal  = databricks_recipient.some.name
    privileges = ["SELECT"]
  }
}

Other access control

You can control Databricks General Permissions through databricks_permissions resource.

Import

The resource can be imported using combination of securable type (table, catalog, foreign_connection, ...) and its name:

import {
  to = databricks_grants.this
  id = "catalog/abc"
}

Alternatively, when using terraform version 1.4 or earlier, import using the terraform import command:

terraform import databricks_grants.this catalog/abc