[DOC] `databricks_grants` needs a note it not being tied to workspace, but still require a workspace host in the configuration?

I'm not sure if it this is a design issue or a documentation issue. If you keep the design, I think documentation would be beneficial.

Affected Resource(s)

databricks_grants

Expected Details

To my limited understanding of Databricks, the unity catalog is somewhat separate from the workspace and seem to exist on an account level (sometimes referred to as the account context). Therefore it is intuitive to expect that it uses an account level provider (similar to creating groups on the account level). To my great surprise however, you are greeted with the error message if you try to authenticate with account level provider:

Error: cannot create grants: Databricks API (/api/2.1/unity-catalog/permissions/catalog/my_catalog) requires you to set host property (or DATABRICKS_HOST env variable) to result of databricks_mws_workspaces.this.workspace_url. This error may happen if you're using provider in both normal and multiworkspace mode. Please refactor your code into different modules. Runnable example that we use for integration testing can be found in this repository at https://registry.terraform.io/providers/databricks/databricks/latest/docs/guides/aws-workspace

This is solved by switching to using a workspace specific provider. What is strange is that it you seem to be able to grant workspace local service principal access even when specifying another workspace's host.

List of things to potentially add/remove:

This is a list of things to manipulate in the docs:

[ ] Link to official documentation describing the unity catalog's relationships with the workspaces
[ ] Add note on what provider configuration you should use
[ ] Add note on how the choice of workspace host affect local groups and service principals of other workspaces and account level groups and service principals (not at all?)

Important Factoids

I asked about this in the Databricks office hours (14/12). They at least confirmed that the unity catalog was indeed outside the workspace. In my mind, this shows that the design of this resource is not ideal.

The unity catalog seem to "exist outside" workspaces. Yet, the grant Terraform resource needs to be tied to a specific workspace hostname for authentication. What is meant by this? It seems we are able to grant our workspace local service principals accesses irregardless of which workspace host we use. Are we doing something wrong?

So basically UC will be top of your account , so it can be associated with all your workspace for the same account.

databricks / terraform-provider-databricks