[Doc] add clarification note for databricks_grants (#4546)

## Changes
- Add a note on how `databricks_grants` work with `MANAGE` permission

## Tests
<!-- 
How is this tested? Please see the checklist below and also describe any
other relevant tests
-->

- [x] relevant change in `docs/` folder

---------

Co-authored-by: Alex Ott <[email protected]>

Author: nkvuong

NEXT_CHANGELOG.md

@@ -12,6 +12,7 @@
 
  * Document management of permissions of `databricks_budget_policy` resource ([#4561](https://github.com/databricks/terraform-provider-databricks/pull/4561))
  * Document `budget_policy_id` in `databricks_app` resource and data sources ([#4557](https://github.com/databricks/terraform-provider-databricks/pull/4557))
+ * Add a note on how `databricks_grants` work with `MANAGE` permission [#4546](https://github.com/databricks/terraform-provider-databricks/pull/4546)
 
 ### Exporter
 

docs/resources/grants.md

@@ -9,7 +9,7 @@ subcategory: "Unity Catalog"
 
 Two different resources help you manage your Unity Catalog grants for a securable. Each of these resources serves a different use case:
 
-- [databricks_grants](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grants): Authoritative. Sets the grants of a securable and replaces any existing grants defined inside or outside of Terraform.
+- [databricks_grants](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grants): Authoritative. Sets the grants of a securable and *replaces* any existing grants defined inside or outside of Terraform.
 - [databricks_grant](https://registry.terraform.io/providers/databricks/databricks/latest/docs/resources/grant): Authoritative for a given principal. Updates the grants of a securable to a single principal. Other principals within the grants for the securables are preserved.
 
 In Unity Catalog all users initially have no access to data. Only Metastore Admins can create objects and can grant/revoke access on individual objects to users and groups. Every securable object in Unity Catalog has an owner. The owner can be any account-level user or group, called principals in general. The principal that creates an object becomes its owner. Owners receive `ALL_PRIVILEGES` on the securable object (e.g., `SELECT` and `MODIFY` on a table), as well as the permission to grant privileges to other principals.
@@ -25,6 +25,8 @@ For the latest list of privilege types that apply to each securable object in Un
 
 Terraform will handle any configuration drift on every `terraform apply` run, even when grants are changed outside of Terraform state.
 
+When applying grants using an identity with [`MANAGE` permission](https://docs.databricks.com/aws/en/data-governance/unity-catalog/manage-privileges/ownership#ownership-versus-the-manage-privilege), their `MANAGE` permission must also be defined, otherwise Terraform will remove their permissions, leading to errors.
+
 Unlike the [SQL specification](https://docs.databricks.com/sql/language-manual/sql-ref-privileges.html#privilege-types), all privileges to be written with underscore instead of space, e.g. `CREATE_TABLE` and not `CREATE TABLE`. Below summarizes which privilege types apply to each securable object in the catalog:
 
 ## Metastore grants
@@ -77,7 +79,7 @@ resource "databricks_grants" "sandbox" {
 
 ## Schema grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VOLUME`, `MANAGE` and `USE_SCHEMA` privileges to [_`catalog.schema`_](schema.md) specified in the `schema` attribute. You can also grant `EXECUTE`, `MODIFY`, `REFRESH`, `SELECT`, `READ_VOLUME`, `WRITE_VOLUME` at the schema level to apply them to the pertinent current and future securable objects within the schema:
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `CREATE_FUNCTION`, `CREATE_TABLE`, `CREATE_VOLUME`, `MANAGE` and `USE_SCHEMA` privileges to [*`catalog.schema`*](schema.md) specified in the `schema` attribute. You can also grant `EXECUTE`, `MODIFY`, `REFRESH`, `SELECT`, `READ_VOLUME`, `WRITE_VOLUME` at the schema level to apply them to the pertinent current and future securable objects within the schema:
 
 ```hcl
 resource "databricks_schema" "things" {
@@ -100,7 +102,7 @@ resource "databricks_grants" "things" {
 
 ## Table grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE`, `SELECT` and `MODIFY` privileges to [_`catalog.schema.table`_](sql_table.md) specified in the `table` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE`, `SELECT` and `MODIFY` privileges to [*`catalog.schema.table`*](sql_table.md) specified in the `table` attribute.
 
 ```hcl
 resource "databricks_grants" "customers" {
@@ -138,7 +140,7 @@ resource "databricks_grants" "things" {
 
 ## View grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE` and `SELECT` privileges to [_`catalog.schema.view`_](sql_table.md) specified in `table` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `MANAGE` and `SELECT` privileges to [*`catalog.schema.view`*](sql_table.md) specified in `table` attribute.
 
 ```hcl
 resource "databricks_grants" "customer360" {
@@ -172,7 +174,7 @@ resource "databricks_grants" "customers" {
 
 ## Volume grants
 
-You can grant `ALL_PRIVILEGES`, `MANAGE`, `READ_VOLUME` and `WRITE_VOLUME` privileges to [_`catalog.schema.volume`_](volume.md) specified in the `volume` attribute.
+You can grant `ALL_PRIVILEGES`, `MANAGE`, `READ_VOLUME` and `WRITE_VOLUME` privileges to [*`catalog.schema.volume`*](volume.md) specified in the `volume` attribute.
 
 ```hcl
 resource "databricks_volume" "this" {
@@ -195,7 +197,7 @@ resource "databricks_grants" "volume" {
 
 ## Registered model grants
 
-You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `EXECUTE`, and `MANAGE` privileges to [_`catalog.schema.model`_](registered_model.md) specified in the `model` attribute.
+You can grant `ALL_PRIVILEGES`, `APPLY_TAG`, `EXECUTE`, and `MANAGE` privileges to [*`catalog.schema.model`*](registered_model.md) specified in the `model` attribute.
 
 ```hcl
 resource "databricks_grants" "customers" {
@@ -213,7 +215,7 @@ resource "databricks_grants" "customers" {
 
 ## Function grants
 
-You can grant `ALL_PRIVILEGES`, `EXECUTE`, and `MANAGE` privileges to _`catalog.schema.function`_ specified in the `function` attribute.
+You can grant `ALL_PRIVILEGES`, `EXECUTE`, and `MANAGE` privileges to *`catalog.schema.function`* specified in the `function` attribute.
 
 ```hcl
 resource "databricks_grants" "udf" {