Manage platform settings inside an existing Azure Databricks workspace. Use the module directly or import supported settings with DataTF. It does not create the Azure workspace.
Usage · Scope · Inputs · Outputs
Configure Databricks unified authentication for the target workspace through environment variables or a configuration profile. Use a workspace endpoint.
terraform {
required_providers {
databricks = {
source = "databricks/databricks"
}
}
}
provider "databricks" {}
module "workspace" {
source = "536tech/workspace/databricks"
version = "0.2.0"
catalogs = {
sales = {
isolation_mode = "ISOLATED"
owner = "data-platform"
}
}
schemas = {
sales = ["bronze", "silver"]
}
}Replace the sample names with your catalog and existing owner group.
The input maps default to {}; force_destroy defaults to false.
For existing objects, follow the adoption guide and require an imports-only plan.
| State | Supported settings |
|---|---|
| Workspace | Cluster policies, pools, SQL warehouses, secret scopes, service principals, and workspace permissions |
| Workspace or shared | Catalogs, schemas, storage credentials, external locations, grants, and workspace bindings |
Use one state per workspace and one shared state per metastore. Keep each object in one state. Azure resources, metastore setup, account role assignments, workloads, stored data, and secret values remain outside this module. See ownership rules and validation for the exact boundaries.
- Workspace example
- Shared Unity Catalog example
- DataTF adoption and import addresses
- Tests and integration evidence
This pattern module combines ten independently released resource modules. Each dependency uses an exact version. A resource module release does not change this pattern's implementation until a pattern release selects and tests that version.
| Child module | Registry module | Pinned version |
|---|---|---|
catalog |
536tech/catalog/databricks | 0.1.0 |
schema |
536tech/schema/databricks | 0.1.0 |
storage_credential |
536tech/storage-credential/databricks | 0.1.0 |
external_location |
536tech/external-location/databricks | 0.1.0 |
workspace_binding |
536tech/workspace-binding/databricks | 0.1.0 |
cluster_policy |
536tech/cluster-policy/databricks | 0.1.0 |
instance_pool |
536tech/instance-pool/databricks | 0.1.0 |
warehouse |
536tech/sql-warehouse/databricks | 0.1.0 |
secret_scope |
536tech/secret-scope/databricks | 0.1.0 |
service_principal |
536tech/service-principal/databricks | 0.1.0 |
Use a resource module directly when you need one component. Use this pattern for DataTF exports or a complete set of supported workspace settings. Configure providers and state in the calling root. See the upgrade guide to move from the bundled submodules in version 0.1.1.
The following reference is generated by terraform-docs.
The following requirements are needed by this module:
-
terraform (>= 1.5.0)
-
databricks (>= 1.128.0, < 2.0.0)
The following input variables are optional (have default values):
Description: Direct grants ON a catalog. Shape: catalog name -> principal -> [privileges].
Principals: groups/users by name or email; service principals by readable alias.
Type: map(map(list(string)))
Default: {}
Description: Catalogs to manage. Key = catalog name; value = catalog settings.
A catalog must be declared here before its schemas or grants can be added.
Type:
map(object({
isolation_mode = string
owner = string
comment = optional(string)
storage_root = optional(string)
properties = optional(map(string))
}))Default: {}
Description: Cluster policies. Key = policy name; value = policy settings.
Set exactly one of definition or policy_family_id. Permissions are nested inline.
The type is any rather than map(object(...)) on purpose: definition,
policy_family_definition_overrides, and libraries hold arbitrary JSON, and Terraform
cannot unify two map elements whose any attributes have different shapes.
The validation blocks below enforce the parts of the shape that are fixed.
Per policy:
description: optional string.definition: optional object, encoded to JSON by the module.policy_family_id: optional string.policy_family_definition_overrides: optional object, encoded to JSON by the module.max_clusters_per_user: optional number.libraries: list of objects, each with one of pypi, maven, cran, whl, jar, egg, or requirements.permissions: list of objects withpermission_leveland exactly one principal field.
The principal field isgroup_name,user_name, orservice_principal_name.
Type: any
Default: {}
Description: Direct grants ON an external location.
Shape: location name -> principal -> [privileges].
Type: map(map(list(string)))
Default: {}
Description: External locations. Key = location name; value = settings including url and credential_name.
credential_name can reference a credential managed here or an existing shared credential.
Type:
map(object({
url = string
credential_name = string
isolation_mode = string
owner = string
read_only = bool
fallback = bool
enable_file_events = bool
comment = optional(string)
}))Default: {}
Description: Service principals managed by another Terraform root.
Key = readable alias; value = Databricks application ID.
Type: map(string)
Default: {}
Description: Allow Terraform to delete Unity Catalog securables that still contain objects.
Type: bool
Default: false
Description: Instance pools. Key = pool name; value = pool settings.
Type:
map(object({
node_type_id = string
min_idle_instances = number
idle_instance_autotermination_minutes = number
enable_elastic_disk = bool
preloaded_spark_versions = list(string)
max_capacity = optional(number)
custom_tags = optional(map(string))
azure_attributes = optional(object({
availability = optional(string)
spot_bid_max_price = optional(number)
}))
permissions = list(object({
permission_level = string
group_name = optional(string)
user_name = optional(string)
service_principal_name = optional(string)
}))
}))Default: {}
Description: Direct grants ON a schema. Shape: catalog -> schema -> principal -> [privileges].
Type: map(map(map(list(string))))
Default: {}
Description: Schema descriptions. Shape: catalog -> schema -> comment.
Type: map(map(string))
Default: {}
Description: Custom managed storage location per schema. Shape: catalog -> schema -> URL.
Type: map(map(string))
Default: {}
Description: Schemas to manage. Key = catalog name; value = list of schema names in that catalog.
The catalog key must also exist in catalogs. An empty list manages the catalog only.
Type: map(list(string))
Default: {}
Description: Secret scopes (prefer Key Vault-backed). Key = scope name; value = settings.
ACLs are nested inline under acls: principal -> permission. Do not put secret values here.
Type:
map(object({
acls = optional(map(string))
keyvault_metadata = optional(object({
resource_id = string
dns_name = string
}))
}))Default: {}
Description: Service principals. Key = readable alias; value = display name and entitlements.
workspace_consume is mutually exclusive with workspace_access and databricks_sql_access,
so set it only when the principal has the consume-only entitlement.
Type:
map(object({
allow_cluster_create = bool
allow_instance_pool_create = bool
databricks_sql_access = bool
workspace_access = bool
display_name = optional(string)
workspace_consume = optional(bool)
}))Default: {}
Description: Direct grants ON a storage credential.
Shape: credential name -> principal -> [privileges].
Type: map(map(list(string)))
Default: {}
Description: Unity Catalog storage credentials. Key = credential name; value = settings (for Azure, an azure_managed_identity that references an existing access connector).
Type:
map(object({
isolation_mode = string
owner = string
read_only = bool
comment = optional(string)
azure_managed_identity = optional(object({
access_connector_id = string
managed_identity_id = optional(string)
}))
}))Default: {}
Description: SQL warehouses. Key = warehouse name; value = warehouse settings.
Type:
map(object({
cluster_size = string
min_num_clusters = number
max_num_clusters = number
auto_stop_mins = number
warehouse_type = string
enable_photon = bool
enable_serverless_compute = bool
spot_instance_policy = optional(string)
tags = optional(map(string))
permissions = list(object({
permission_level = string
group_name = optional(string)
user_name = optional(string)
service_principal_name = optional(string)
}))
}))Default: {}
Description: Unity Catalog workspace bindings. The map key is the provider import ID:
workspace_id|securable_type|securable_name.
Type:
map(object({
workspace_id = number
securable_name = string
securable_type = string
binding_type = string
}))Default: {}
The following outputs are exported:
Description: Managed catalogs. Key = catalog name; value = catalog id.
Description: Managed cluster policies. Key = policy name; value = policy id.
Description: Managed external locations. Key = location name; value = location id.
Description: Managed instance pools. Key = pool name; value = pool id.
Description: Managed schemas. Key = catalog.schema; value = schema id.
Description: Managed secret scopes. Key = scope name; value = scope id.
Description: Managed service principals. Key = tfvars key; value = application id.
Description: Managed service principals. Key = tfvars key; value = service principal id.
Description: Managed storage credentials. Key = credential name; value = credential id.
Description: Managed SQL warehouses. Key = warehouse name; value = warehouse id.
Description: Managed workspace bindings. Key = provider import ID; value = resource ID.