Document new fields in databricks_model_serving and deprecate invalid_keywords and valid_topics in AI Gateway configuration (#4851)

## Changes
<!-- Summary of your changes that are easy to understand -->

Should be merged after #4844 

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

- [x] `make test` run locally
- [x] relevant change in `docs/` folder
- [ ] covered with integration tests in `internal/acceptance`
- [ ] using Go SDK
- [ ] using TF Plugin Framework
- [x] has entry in `NEXT_CHANGELOG.md` file

Author: alexott

NEXT_CHANGELOG.md

@@ -10,6 +10,7 @@
 * Use single-node cluster for `databricks_sql_permissions` ([#4813](https://github.com/databricks/terraform-provider-databricks/pull/4813)).
 * Allow to retrieve service principal data by SCIM ID ([#3142](https://github.com/databricks/terraform-provider-databricks/pull/3142)).
 * Add support for Lakebase `databricks_database_instance` in  `databricks_permissions` ([#4824](https://github.com/databricks/terraform-provider-databricks/pull/4824)).
+* Document new fields in `databricks_model_serving` and deprecate `invalid_keywords` and `valid_topics` in AI Gateway configuration ([#4851](https://github.com/databricks/terraform-provider-databricks/pull/4851)).
 * Added support for Alert V2 in `databricks_permissions` ([#4831](https://github.com/databricks/terraform-provider-databricks/pull/4831)).
 * Replace instead of dropping Delta `databricks_sql_table` ([#2424](https://github.com/databricks/terraform-provider-databricks/pull/2424)).
 * Added `clean_rooms_clean_room` resource and data sources ([#4844](https://github.com/databricks/terraform-provider-databricks/pull/4844)).

docs/resources/model_serving.md

@@ -132,6 +132,7 @@ The following arguments are supported:
 * `ai_gateway` - (Optional) A block with AI Gateway configuration for the serving endpoint. *Note: only external model endpoints are supported as of now.*
 * `route_optimized` - (Optional) A boolean enabling route optimization for the endpoint. *Note: only available for custom models.*
 * `budget_policy_id` - (Optiona) The Budget Policy ID set for this serving endpoint.
+* `description` - (Optional) The description of the model serving endpoint.
 
 ### served_entities Configuration Block
 
@@ -237,7 +238,8 @@ The following arguments are supported:
 ### rate_limits Configuration Block
 
 * `calls` - (Required) Used to specify how many calls are allowed for a key within the renewal_period.
-* `key` - (Optional) Key field for a serving endpoint rate limit. Currently, only `user` and `endpoint` are supported, with `endpoint` being the default if not specified.
+* `key` - (Optional) Key field for a serving endpoint rate limit. Currently, `user`, `user_group`, `service_principal`, and `endpoint` are supported, with `endpoint` being the default if not specified.
+* `principal` - (Optional) Principal field for a user, user group, or service principal to apply rate limiting to. Accepts a user email, group name, or service principal application ID.
 * `renewal_period` - (Required) Renewal period field for a serving endpoint rate limit. Currently, only `minute` is supported.
 
 ### ai_gateway Configuration Block
@@ -246,8 +248,8 @@ The following arguments are supported:
   * `enabled` -  Whether to enable traffic fallback. When a served entity in the serving endpoint returns specific error codes (e.g. 500), the request will automatically be round-robin attempted with other served entities in the same endpoint, following the order of served entity list, until a successful response is returned.
 * `guardrails` - (Optional) Block with configuration for AI Guardrails to prevent unwanted data and unsafe data in requests and responses. Consists of the following attributes:
   * `input` - A block with configuration for input guardrail filters:
-    * `invalid_keywords` - List of invalid keywords. AI guardrail uses keyword or string matching to decide if the keyword exists in the request or response content.
-    * `valid_topics` - The list of allowed topics. Given a chat request, this guardrail flags the request if its topic is not in the allowed topics.
+    * `invalid_keywords` - (Deprecated) List of invalid keywords. AI guardrail uses keyword or string matching to decide if the keyword exists in the request or response content.
+    * `valid_topics` - (Deprecated) The list of allowed topics. Given a chat request, this guardrail flags the request if its topic is not in the allowed topics.
     * `safety` - the boolean flag that indicates whether the safety filter is enabled.
     * `pii` - Block with configuration for guardrail PII filter:
       * `behavior` - a string that describes the behavior for PII filter. Currently only `BLOCK` value is supported.

serving/resource_model_serving.go

@@ -166,6 +166,11 @@ func ResourceModelServing() common.Resource {
 			common.CustomizeSchemaPath(m, "config", "traffic_config", "routes", "served_model_name").SetCustomSuppressDiff(suppressRouteModelEntityNameDiff)
 			common.CustomizeSchemaPath(m, "config", "traffic_config", "routes", "served_entity_name").SetCustomSuppressDiff(suppressRouteModelEntityNameDiff)
 
+			common.MustSchemaPath(m, "ai_gateway", "guardrails", "input", "invalid_keywords").Deprecated = "Please use 'pii' and 'safety' instead."
+			common.MustSchemaPath(m, "ai_gateway", "guardrails", "input", "valid_topics").Deprecated = "Please use 'pii' and 'safety' instead."
+			common.MustSchemaPath(m, "ai_gateway", "guardrails", "output", "invalid_keywords").Deprecated = "Please use 'pii' and 'safety' instead."
+			common.MustSchemaPath(m, "ai_gateway", "guardrails", "output", "valid_topics").Deprecated = "Please use 'pii' and 'safety' instead."
+
 			// route_optimized cannot be updated.
 			common.CustomizeSchemaPath(m, "route_optimized").SetForceNew()