Fix spurious diffs in model serving resources due to API ordering (#5188)

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

The model serving API returns served_models and served_entities in
non-deterministic order (typically alphabetically by name), but
Terraform treats them as ordered lists. This caused spurious diffs when
the API returned items in a different order than specified in the HCL
configuration.

Solution:
- Added reorderByName() generic helper function to re-order API response
slices to match the user's HCL configuration order
- Updated preserveConfigOrder() to use the helper for both served_models
and served_entities
- Updated preserveConfigOrderPt() for provisioned throughput endpoints
- Added comprehensive unit tests with 11 test cases

The fix preserves user intent by maintaining the order specified in the
configuration while handling the API's non-deterministic behavior.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


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

- [x] `make test` run locally
- [ ] 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

Co-authored-by: Claude <[email protected]>

Author: alexott

NEXT_CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Bug Fixes
 
+* Fixed spurious diffs in `databricks_model_serving` and `databricks_model_serving_provisioned_throughput` resources when the API returns `served_models` or `served_entities` in a different order than specified in the configuration ([#5188](https://github.com/databricks/terraform-provider-databricks/pull/5188)).
+
 ### Documentation
 
 * Improve documentation about `preloaded_docker_images.basic_auth` in `databricks_cluster` and `databricks_instance_pool` ([#5154](https://github.com/databricks/terraform-provider-databricks/pull/5154)).

serving/preserve_order_test.go

@@ -0,0 +1,181 @@
+package serving
+
+import (
+	"testing"
+
+	"github.com/databricks/databricks-sdk-go/service/serving"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestReorderByName(t *testing.T) {
+	t.Run("reorders items to match config order", func(t *testing.T) {
+		configNames := []string{"prod", "staging", "dev"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "dev", ModelName: "model1"},
+			{Name: "prod", ModelName: "model2"},
+			{Name: "staging", ModelName: "model3"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Equal(t, "prod", result[0].Name)
+		assert.Equal(t, "staging", result[1].Name)
+		assert.Equal(t, "dev", result[2].Name)
+	})
+
+	t.Run("handles alphabetical API ordering", func(t *testing.T) {
+		// Simulates the actual bug: API returns alphabetically, config has different order
+		configNames := []string{"prod_model", "candidate_model"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "candidate_model", ModelVersion: "2"},
+			{Name: "prod_model", ModelVersion: "1"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Equal(t, "prod_model", result[0].Name)
+		assert.Equal(t, "candidate_model", result[1].Name)
+	})
+
+	t.Run("appends extra API items not in config", func(t *testing.T) {
+		configNames := []string{"model1", "model2"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "model2", ModelName: "m2"},
+			{Name: "model3", ModelName: "m3"}, // Not in config
+			{Name: "model1", ModelName: "m1"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Len(t, result, 3)
+		assert.Equal(t, "model1", result[0].Name)
+		assert.Equal(t, "model2", result[1].Name)
+		assert.Equal(t, "model3", result[2].Name) // Appended at end
+	})
+
+	t.Run("handles empty config names", func(t *testing.T) {
+		configNames := []string{}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "model1"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Equal(t, apiItems, result) // Returns original unchanged
+	})
+
+	t.Run("handles empty API items", func(t *testing.T) {
+		configNames := []string{"model1"}
+		apiItems := []serving.ServedModelOutput{}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Empty(t, result)
+	})
+
+	t.Run("handles nil slices", func(t *testing.T) {
+		var apiItems []serving.ServedModelOutput
+		result := reorderByName([]string{"model1"}, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Nil(t, result)
+	})
+
+	t.Run("maintains order when already correct", func(t *testing.T) {
+		configNames := []string{"model1", "model2", "model3"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "model1"},
+			{Name: "model2"},
+			{Name: "model3"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Equal(t, "model1", result[0].Name)
+		assert.Equal(t, "model2", result[1].Name)
+		assert.Equal(t, "model3", result[2].Name)
+	})
+
+	t.Run("works with served entities", func(t *testing.T) {
+		configNames := []string{"entity_b", "entity_a"}
+		apiItems := []serving.ServedEntityOutput{
+			{Name: "entity_a", EntityName: "cat.sch.entity_a"},
+			{Name: "entity_b", EntityName: "cat.sch.entity_b"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(e serving.ServedEntityOutput) string { return e.Name })
+
+		assert.Equal(t, "entity_b", result[0].Name)
+		assert.Equal(t, "entity_a", result[1].Name)
+	})
+
+	t.Run("handles partial matches", func(t *testing.T) {
+		// Some items in config don't exist in API response (shouldn't happen, but be safe)
+		configNames := []string{"model1", "model2", "model3"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "model2"},
+			{Name: "model1"},
+			// model3 doesn't exist in API
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Len(t, result, 2)
+		assert.Equal(t, "model1", result[0].Name)
+		assert.Equal(t, "model2", result[1].Name)
+	})
+
+	t.Run("handles single item", func(t *testing.T) {
+		configNames := []string{"only_model"}
+		apiItems := []serving.ServedModelOutput{
+			{Name: "only_model", ModelName: "m1"},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		assert.Len(t, result, 1)
+		assert.Equal(t, "only_model", result[0].Name)
+	})
+
+	t.Run("preserves all item properties", func(t *testing.T) {
+		configNames := []string{"model2", "model1"}
+		apiItems := []serving.ServedModelOutput{
+			{
+				Name:               "model1",
+				ModelName:          "my_model",
+				ModelVersion:       "1",
+				ScaleToZeroEnabled: true,
+			},
+			{
+				Name:               "model2",
+				ModelName:          "another_model",
+				ModelVersion:       "3",
+				ScaleToZeroEnabled: false,
+			},
+		}
+
+		result := reorderByName(configNames, apiItems,
+			func(m serving.ServedModelOutput) string { return m.Name })
+
+		// Check first item (model2)
+		assert.Equal(t, "model2", result[0].Name)
+		assert.Equal(t, "another_model", result[0].ModelName)
+		assert.Equal(t, "3", result[0].ModelVersion)
+		assert.False(t, result[0].ScaleToZeroEnabled)
+
+		// Check second item (model1)
+		assert.Equal(t, "model1", result[1].Name)
+		assert.Equal(t, "my_model", result[1].ModelName)
+		assert.Equal(t, "1", result[1].ModelVersion)
+		assert.True(t, result[1].ScaleToZeroEnabled)
+	})
+}

serving/resource_model_serving.go

@@ -172,6 +172,82 @@ func cleanWorkloadSize(s map[string]*schema.Schema, d *schema.ResourceData, apiR
 	}
 }
 
+// reorderByName is a generic helper that re-orders a slice of items from the API response
+// to match the order of names in the config. Items are matched by name, and any items in
+// the API response that aren't in the config are appended at the end.
+//
+// Parameters:
+//   - configNames: ordered list of names from the user's HCL configuration
+//   - apiItems: slice of items from the API response
+//   - getName: function to extract the name from an API item
+//
+// Returns: re-ordered slice maintaining the same type as apiItems
+func reorderByName[T any](configNames []string, apiItems []T, getName func(T) string) []T {
+	if len(configNames) == 0 || len(apiItems) == 0 {
+		return apiItems
+	}
+
+	reordered := make([]T, 0, len(apiItems))
+
+	// First pass: add items in config order
+	for _, configName := range configNames {
+		for _, apiItem := range apiItems {
+			if getName(apiItem) == configName {
+				reordered = append(reordered, apiItem)
+				break
+			}
+		}
+	}
+
+	// Second pass: append any items from API that weren't in config
+	for _, apiItem := range apiItems {
+		found := false
+		for _, reorderedItem := range reordered {
+			if getName(reorderedItem) == getName(apiItem) {
+				found = true
+				break
+			}
+		}
+		if !found {
+			reordered = append(reordered, apiItem)
+		}
+	}
+
+	return reordered
+}
+
+// preserveConfigOrder re-orders the served_models and served_entities in the API response
+// to match the order specified in the HCL configuration. This prevents spurious diffs when
+// the API returns items in a different order (e.g., alphabetically) than submitted.
+func preserveConfigOrder(s map[string]*schema.Schema, d *schema.ResourceData, apiResponse *serving.EndpointCoreConfigOutput) {
+	var config serving.CreateServingEndpoint
+	common.DataToStructPointer(d, s, &config)
+
+	if config.Config == nil || apiResponse == nil {
+		return
+	}
+
+	// Re-order served_models to match config order
+	if len(config.Config.ServedModels) > 0 && len(apiResponse.ServedModels) > 0 {
+		configNames := make([]string, len(config.Config.ServedModels))
+		for i, model := range config.Config.ServedModels {
+			configNames[i] = model.Name
+		}
+		apiResponse.ServedModels = reorderByName(configNames, apiResponse.ServedModels,
+			func(m serving.ServedModelOutput) string { return m.Name })
+	}
+
+	// Re-order served_entities to match config order
+	if len(config.Config.ServedEntities) > 0 && len(apiResponse.ServedEntities) > 0 {
+		configNames := make([]string, len(config.Config.ServedEntities))
+		for i, entity := range config.Config.ServedEntities {
+			configNames[i] = entity.Name
+		}
+		apiResponse.ServedEntities = reorderByName(configNames, apiResponse.ServedEntities,
+			func(e serving.ServedEntityOutput) string { return e.Name })
+	}
+}
+
 func ResourceModelServing() common.Resource {
 	s := common.StructToSchema(
 		serving.CreateServingEndpoint{},
@@ -274,6 +350,7 @@ func ResourceModelServing() common.Resource {
 				}
 			}
 			cleanWorkloadSize(s, d, endpoint.Config)
+			preserveConfigOrder(s, d, endpoint.Config)
 
 			err = common.StructToData(*endpoint, s, d)
 			if err != nil {

serving/resource_model_serving_provisioned_throughput.go

@@ -14,6 +14,28 @@ const (
 	defaultPtProvisionTimeout = 10 * time.Minute
 )
 
+// preserveConfigOrderPt re-orders the served_entities in the API response for provisioned
+// throughput endpoints to match the order specified in the HCL configuration. This prevents
+// spurious diffs when the API returns items in a different order (e.g., alphabetically).
+func preserveConfigOrderPt(s map[string]*schema.Schema, d *schema.ResourceData, apiResponse *serving.EndpointCoreConfigOutput) {
+	var config serving.CreatePtEndpointRequest
+	common.DataToStructPointer(d, s, &config)
+
+	if apiResponse == nil {
+		return
+	}
+
+	// Re-order served_entities to match config order
+	if len(config.Config.ServedEntities) > 0 && len(apiResponse.ServedEntities) > 0 {
+		configNames := make([]string, len(config.Config.ServedEntities))
+		for i, entity := range config.Config.ServedEntities {
+			configNames[i] = entity.Name
+		}
+		apiResponse.ServedEntities = reorderByName(configNames, apiResponse.ServedEntities,
+			func(e serving.ServedEntityOutput) string { return e.Name })
+	}
+}
+
 func ResourceModelServingProvisionedThroughput() common.Resource {
 	s := common.StructToSchema(
 		serving.CreatePtEndpointRequest{},
@@ -72,6 +94,7 @@ func ResourceModelServingProvisionedThroughput() common.Resource {
 			if err != nil {
 				return err
 			}
+			preserveConfigOrderPt(s, d, endpoint.Config)
 			err = common.StructToData(*endpoint, s, d)
 			if err != nil {
 				return err