Add user guide for new behaviours with UC by default (#3318)

* add uc by default guide

* make fmt-docs

Author: nkvuong

docs/guides/troubleshooting.md

@@ -197,7 +197,7 @@ If you want to enforce a specific authorization method, you can set the `auth_ty
 
 ```hcl
 provider "databricks" {
-  ...
+  # other configurations
   auth_type = "pat"
 }
 ```

docs/guides/unity-catalog-azure.md

@@ -5,7 +5,7 @@ page_title: "Unity Catalog set up on Azure"
 # Deploying pre-requisite resources and enabling Unity Catalog
 
 **Note**
-If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you.
+If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you. See [this guide](unity-catalog-default.md) instead.
 
 **Note**
 Except for metastore, metastore assignment and storage credential objects, Unity Catalog APIs are accessible via **workspace-level APIs**. This design may change in the future.

docs/guides/unity-catalog-default.md

@@ -0,0 +1,97 @@
+---
+page_title: "Working with Unity Catalog by default"
+---
+
+# Working with Unity Catalog by default
+
+Databricks began to [enable new workspaces for Unity Catalog automatically](https://learn.microsoft.com/en-us/azure/databricks/data-governance/unity-catalog/get-started#--automatic-enablement-of-unity-catalog) on November 9, 2023, with a rollout proceeding gradually across accounts. Workspaces that were enabled automatically have the following properties:
+
+- An automatically-provisioned Unity Catalog metastore (unless a Unity Catalog metastore already existed for the workspace region).
+- Default privileges for workspace admins, such as the ability to create a catalog or an external database connection.
+- No metastore admin (unless an existing Unity Catalog metastore was used and a metastore admin was already assigned).
+- No metastore-level storage for managed tables and managed volumes (unless an existing Unity Catalog metastore with metastore-level storage was used).
+- A workspace catalog, which, when originally provisioned, is named after your workspace.
+
+This removes the need to manually enable Unity Catalog following [this guide](unity-catalog.md). However, you may need to adjust your Terraform configuration to account for this accordingly
+
+## Removing default privileges for workspace admins
+
+An account admin may decide to remove the default privileges granted to workspace admins, such as the ability to create a catalog or connection. This can be achieved using [databricks_grants](../resources/grants.md), which will override any metastore-level grants not defined in Terraform
+
+```hcl
+data "databricks_current_metastore" "this" {
+}
+
+resource "databricks_grants" "this" {
+  metastore = data.databricks_metastore.this.id
+  grant {
+    principal  = "Data Engineers"
+    privileges = ["CREATE_CATALOG", "CREATE_EXTERNAL_LOCATION"]
+  }
+  grant {
+    principal  = "Data Sharer"
+    privileges = ["CREATE_RECIPIENT", "CREATE_SHARE"]
+  }
+}
+```
+
+## Avoiding the automatically-provisioned Unity Catalog metastore
+
+An account admin may pre-create metastores with specific admins in all regions that workspaces will be deployed. This will ensure that new workspaces are automatically assigned to the correct metastore
+
+```hcl
+variable "regions" {
+  default = ["ap-northeast-1", "eu-west-1"]
+}
+
+resource "databricks_metastore" "this" {
+  for_each = toset(var.regions)
+  name     = "metastore-${each.value}"
+  region   = each.value
+}
+```
+
+## Mandating storage for new catalogs
+
+The automatically-provisioned Unity Catalog metastore does not have metastore-level storage, which means each new catalog has to have a storage location defined
+
+```hcl
+# this would fail with "storage location required" error
+resource "databricks_catalog" "sandbox" {
+  name = "sandbox"
+}
+```
+
+## Using the workspace catalog
+
+The automatically-provisioned workspace catalog is named after the workspace and initially is bound to that workspace only.
+
+To retrieve this catalog using [databricks_catalogs](../data-sources/catalogs.md)
+
+```hcl
+variable workspace_name {}
+
+data "databricks_catalogs" "all" {}
+
+locals {
+  default_catalog = [for each in data.databricks_catalogs.all.ids : each if strcontains(each, var.workspace_name)]
+}
+```
+
+This can then be used to create objects under this catalog, e.g.
+
+```hcl
+resource "databricks_schema" "sandbox" {
+  catalog_name = local.default_catalog[0]
+  name         = "sandbox"
+}
+```
+
+Or bind this catalog to more workspaces
+
+```hcl
+resource "databricks_catalog_workspace_binding" "default_catalog" {
+  securable_name = local.default_catalog[0]
+  workspace_id   = databricks_mws_workspaces.other.workspace_id
+}
+```

docs/guides/unity-catalog-gcp.md

@@ -5,7 +5,7 @@ page_title: "Unity Catalog set up on Google Cloud"
 # Deploying pre-requisite resources and enabling Unity Catalog
 
 **Note**
-If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you.
+If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you. See [this guide](unity-catalog-default.md) instead.
 
 **Note**
 Except for metastore, metastore assignment and storage credential objects, Unity Catalog APIs are accessible via **workspace-level APIs**. This design may change in the future.

docs/guides/unity-catalog.md

@@ -5,7 +5,7 @@ page_title: "Unity Catalog set up on AWS"
 # Deploying pre-requisite resources and enabling Unity Catalog
 
 **Note**
-If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you.
+If your workspace was enabled for Unity Catalog automatically, this guide does not apply to you. See [this guide](unity-catalog-default.md) instead.
 
 **Note**
 Except for metastore, metastore assignment and storage credential objects, Unity Catalog APIs are accessible via **workspace-level APIs**. This design may change in the future.

docs/resources/file.md

@@ -34,11 +34,11 @@ resource "databricks_schema" "things" {
 }
 
 resource "databricks_volume" "this" {
-  name             = "quickstart_volume"
-  catalog_name     = databricks_catalog.sandbox.name
-  schema_name      = databricks_schema.things.name
-  volume_type      = "MANAGED"
-  comment          = "this volume is managed by terraform"
+  name         = "quickstart_volume"
+  catalog_name = databricks_catalog.sandbox.name
+  schema_name  = databricks_schema.things.name
+  volume_type  = "MANAGED"
+  comment      = "this volume is managed by terraform"
 }
 
 resource "databricks_file" "this" {
@@ -56,7 +56,7 @@ resource "databricks_file" "init_script" {
     echo "Hello World"
     EOT
   )
-  path   = "${databricks_volume.this.volume_path}/fileName"
+  path = "${databricks_volume.this.volume_path}/fileName"
 }
 ```
 

docs/resources/grants.md

@@ -35,7 +35,7 @@ You can grant `CREATE_CATALOG`, `CREATE_CONNECTION`, `CREATE_EXTERNAL_LOCATION`,
 
 ```hcl
 resource "databricks_grants" "sandbox" {
-  metastore    = "metastore_id"
+  metastore = "metastore_id"
   grant {
     principal  = "Data Engineers"
     privileges = ["CREATE_CATALOG", "CREATE_EXTERNAL_LOCATION"]

docs/resources/share.md

@@ -37,12 +37,12 @@ Creating a Delta Sharing share and add a schema to it(including all current and
 
 ```hcl
 resource "databricks_share" "schema_share" {
-    name = "schema_share"
-    object {
-        name = "catalog_name.schema_name"
-        data_object_type = "SCHEMA"
-        history_data_sharing_status = "ENABLED"
-    }
+  name = "schema_share"
+  object {
+    name                        = "catalog_name.schema_name"
+    data_object_type            = "SCHEMA"
+    history_data_sharing_status = "ENABLED"
+  }
 }
 ```
 

docs/resources/sql_widget.md

@@ -14,25 +14,25 @@ A widget is always tied to a [dashboard](sql_dashboard.md). Every dashboard may
 ```hcl
 resource "databricks_sql_widget" "d1w1" {
   dashboard_id = databricks_sql_dashboard.d1.id
-  text = "Hello! I'm a **text widget**!"
+  text         = "Hello! I'm a **text widget**!"
 
   position {
     size_x = 3
     size_y = 4
-    pos_x = 0
-    pos_y = 0
+    pos_x  = 0
+    pos_y  = 0
   }
 }
 
 resource "databricks_sql_widget" "d1w2" {
-  dashboard_id = databricks_sql_dashboard.d1.id
+  dashboard_id     = databricks_sql_dashboard.d1.id
   visualization_id = databricks_sql_visualization.q1v1.id
 
   position {
     size_x = 3
     size_y = 4
-    pos_x = 3
-    pos_y = 0
+    pos_x  = 3
+    pos_y  = 0
   }
 }
 ```

docs/resources/vector_search_endpoint.md

@@ -11,7 +11,7 @@ This resource allows you to create [Vector Search Endpoint](https://docs.databri
 
 ```hcl
 resource "databricks_vector_search_endpoint" "this" {
-  name = "vector-search-test"
+  name          = "vector-search-test"
   endpoint_type = "STANDARD"
 }
 ```