[DOC] Fix Terraform docs for databricks_permissions and OBO tokens

[arpitjasa-db]

Hi there,

Thank you for opening an issue. Please note that we try to keep the Databricks Provider issue tracker reserved for bug reports and feature requests. For general Terraform questions, please see: https://www.terraform.io/community.html.
This template is for both adding enhancement as well as pointing out issues with the provider documentation.

Affected Resource(s)

https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs/resources/permissions#argument-reference
https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs/resources/obo_token
https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs#authentication
https://registry.terraform.io/providers/databrickslabs/databricks/latest/docs/resources/permissions#import

List of things to potentially add/remove:

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

• Make it clear that permissions for resources must be set up through an additional resource called databricks_permissions instead of as a resource argument. Also that creating this object will overwrite any existing permissions (unless imported), and that any changes made to permissions not via Terraform will also be overwritten on a subsequent terraform apply (unless the state entry is deleted and then imported again).
• Arguments for databricks_permissions documentation needs to be updated for the “Exactly one of the following attributes is required:” section to reflect all of the new permission resource types (experiments, SQL, etc.).
• The DB TF docs for OBO token list a way to use the databricks_permission resource to give this permission to my SP, but then it would remove this ability from the users group, which is definitely not what we want. We should update the doc code to say something like this instead while making it more striking and clear that creating databricks_permissions will overwrite the existing permissions instead of the single sentence we see:

resource "databricks_permissions" "token_usage" {
  provider      = databricks.primary
  authorization = "tokens"
  access_control {
    group_name       = "users"
    permission_level = "CAN_USE"
  }
  access_control {
    service_principal_name = databricks_service_principal.sp.application_id
    permission_level       = "CAN_USE"
  }
}

• We should make it more clear for credentials in general that ~/.databrickscfg can be used in unexpected ways and that empty strings for tokens won’t error out explicitly but rather it defaults to the local credentials saved. This can result in a lot of unintended behavior since many people may have local credentials saved that they do not want Terraform to use.
• Since importing permissions seems like a very natural step to follow, especially as seen above, we should expand the import permissions section to include examples of how to use the command since the current one-liner command is very unclear. This is especially true because many resources have multiple fields that can serve as the identification field. It may even be better and clearer to include an import example under each section instead of a catch-all import section at the end to account for these resource-specific use cases, and because <object type> is not a clear field to fill in.

[nfx]

@arpitjasa-db Pull requests are more than welcome. Doc sources are located in docs folder.

[nfx]

Thank you for the feature request! Currently, the team operates in a limited capacity, carefully prioritizing, and we cannot provide a timeline to implement this feature. Please make a Pull Request if you'd like to see this feature sooner, and we'll guide you through the journey.