[DOC] Unity Catalog: which operations need account- versus workspace-level authentication?

[PaulCornellDB]

Affected Resource(s)

• All Unity Catalog-related Resources pages
• All Unity Catalog-related Data Sources pages
• "Unity Catalog setup on AWS": https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs/guides/unity-catalog
• "Unity Catalog setup on Azure": https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs/guides/unity-catalog-azure

Request

Users are using Terraform to set up Unity Catalog and their entire permission structure. They are encountering "failures" with the Terraform module after a recent upgrade to Databricks Terraform provider v1.24. They assume this line in the accompanying release notes "Added account-level API support for Unity Catalog objects" meant that all Unity Catalog resources are now supported at the account-level.

From one reporting user: it is "not very clear at this point in the docs which need workspace level api and account level api so we just assumed any unity resource is acct level"

You use the account APIs to create metastores and assign to workspaces. You use the workspace APIs for everything ‘under a metastore.' However, in the latest release notes: it noted "Added account-level API support for Unity Catalog objects (#2182)." Which signified to some users to assume that all Unity Catalog objects were now at the account level and needed account level APIs. However, this was not the case.

So this request is to make it clear in the docs where applicable that the account-level APIs and account level provider should be used to create metastores and assign those metastores to workspaces. While anything below that should be using the workspace-level APIs and the workspace provider should be used to anything else.