CLOUDP-446873: Skip connection update for alias migration

Treats an instance_name to workspace_name transition with the same effective workspace and unchanged connection settings as a state-only update. This avoids an Atlas PATCH that active processors prohibit.

Author: jwongmongodb

.changelog/446873.txt

@@ -0,0 +1,3 @@
+```release-note:bug
+Skips connection API updates when migrating between equivalent instance_name and workspace_name values
+```

docs/guides/stream-instance-to-stream-workspace-migration-guide.md

@@ -86,7 +86,7 @@ resource "mongodbatlas_stream_connection" "example" {
 }
 ```
 
-Use the same `instance_name` to `workspace_name` change for stream processors. When both attributes resolve to the same workspace, updating a stream connection is an in-place state migration and does not replace the connection. An alias-only stream processor update also does not stop or restart the processor.
+Use the same `instance_name` to `workspace_name` change for stream processors. When both attributes resolve to the same workspace, the provider updates a stream connection in Terraform state only: it does not replace the connection or send an Atlas API update. An alias-only stream processor update also does not stop or restart the processor.
 
 Run `terraform plan` before applying the configuration. Expect the workspace resource to be moved and dependent resources to be updated in place; do not apply a plan that destroys and recreates an unchanged stream connection.
 

internal/service/streamconnection/model_alias_transition_test.go

@@ -0,0 +1,75 @@
+package streamconnection_test
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/types"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/mongodb/terraform-provider-mongodbatlas/internal/service/streamconnection"
+)
+
+func TestIsAliasOnlyTransition(t *testing.T) {
+	legacyState := streamconnection.TFStreamConnectionModel{
+		TFStreamConnectionCommonModel: streamconnection.TFStreamConnectionCommonModel{
+			ID:             types.StringValue("workspace-project-connection"),
+			InstanceName:   types.StringValue("workspace"),
+			WorkspaceName:  types.StringNull(),
+			ProjectID:      types.StringValue("project"),
+			ConnectionName: types.StringValue("connection"),
+			Type:           types.StringValue("Sample"),
+		},
+	}
+
+	testCases := map[string]struct {
+		plan                streamconnection.TFStreamConnectionModel
+		state               streamconnection.TFStreamConnectionModel
+		aliasOnlyTransition bool
+	}{
+		"legacy_to_canonical": {
+			state: legacyState,
+			plan: streamconnection.TFStreamConnectionModel{
+				TFStreamConnectionCommonModel: streamconnection.TFStreamConnectionCommonModel{
+					ID:             types.StringUnknown(),
+					InstanceName:   types.StringNull(),
+					WorkspaceName:  types.StringValue("workspace"),
+					ProjectID:      types.StringValue("project"),
+					ConnectionName: types.StringValue("connection"),
+					Type:           types.StringValue("Sample"),
+				},
+			},
+			aliasOnlyTransition: true,
+		},
+		"different_workspace": {
+			state: legacyState,
+			plan: streamconnection.TFStreamConnectionModel{
+				TFStreamConnectionCommonModel: streamconnection.TFStreamConnectionCommonModel{
+					InstanceName:   types.StringNull(),
+					WorkspaceName:  types.StringValue("other-workspace"),
+					ProjectID:      types.StringValue("project"),
+					ConnectionName: types.StringValue("connection"),
+					Type:           types.StringValue("Sample"),
+				},
+			},
+		},
+		"connection_configuration_changed": {
+			state: legacyState,
+			plan: streamconnection.TFStreamConnectionModel{
+				TFStreamConnectionCommonModel: streamconnection.TFStreamConnectionCommonModel{
+					InstanceName:     types.StringNull(),
+					WorkspaceName:    types.StringValue("workspace"),
+					ProjectID:        types.StringValue("project"),
+					ConnectionName:   types.StringValue("connection"),
+					Type:             types.StringValue("Kafka"),
+					BootstrapServers: types.StringValue("broker:9092"),
+				},
+			},
+		},
+	}
+
+	for name, tc := range testCases {
+		t.Run(name, func(t *testing.T) {
+			assert.Equal(t, tc.aliasOnlyTransition, streamconnection.IsAliasOnlyTransition(&tc.plan, &tc.state))
+		})
+	}
+}

internal/service/streamconnection/model_stream_connection.go

@@ -3,6 +3,7 @@ package streamconnection
 import (
 	"context"
 	"fmt"
+	"reflect"
 
 	"github.com/hashicorp/terraform-plugin-framework-timeouts/resource/timeouts"
 	"github.com/hashicorp/terraform-plugin-framework/diag"
@@ -13,6 +14,28 @@ import (
 	"go.mongodb.org/atlas-sdk/v20250312025/admin"
 )
 
+// IsAliasOnlyTransition reports whether a plan preserves the effective workspace
+// and changes no connection configuration other than its alias representation.
+func IsAliasOnlyTransition(plan, state *TFStreamConnectionModel) bool {
+	if plan.WorkspaceName.IsUnknown() || plan.InstanceName.IsUnknown() || state.WorkspaceName.IsUnknown() || state.InstanceName.IsUnknown() {
+		return false
+	}
+	if plan.WorkspaceName.Equal(state.WorkspaceName) && plan.InstanceName.Equal(state.InstanceName) {
+		return false
+	}
+	if getWorkspaceOrInstanceName(plan) != getWorkspaceOrInstanceName(state) {
+		return false
+	}
+
+	planWithoutAliases := *plan
+	planWithoutAliases.WorkspaceName = state.WorkspaceName
+	planWithoutAliases.InstanceName = state.InstanceName
+	// ID is computed and may be unknown in an update plan even though no
+	// connection setting changed.
+	planWithoutAliases.ID = state.ID
+	return reflect.DeepEqual(planWithoutAliases, *state)
+}
+
 func NewStreamConnectionReq(ctx context.Context, plan *TFStreamConnectionModel) (*admin.StreamsConnection, diag.Diagnostics) {
 	streamConnection := admin.StreamsConnection{
 		Name:             plan.ConnectionName.ValueStringPointer(),

internal/service/streamconnection/resource_stream_connection.go

@@ -296,12 +296,20 @@ func (r *streamConnectionRS) Read(ctx context.Context, req resource.ReadRequest,
 }
 
 func (r *streamConnectionRS) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
-	var streamConnectionPlan TFStreamConnectionModel
+	var streamConnectionPlan, streamConnectionState TFStreamConnectionModel
 	resp.Diagnostics.Append(req.Plan.Get(ctx, &streamConnectionPlan)...)
+	resp.Diagnostics.Append(req.State.Get(ctx, &streamConnectionState)...)
 	if resp.Diagnostics.HasError() {
 		return
 	}
 
+	if IsAliasOnlyTransition(&streamConnectionPlan, &streamConnectionState) {
+		streamConnectionState.InstanceName = streamConnectionPlan.InstanceName
+		streamConnectionState.WorkspaceName = streamConnectionPlan.WorkspaceName
+		resp.Diagnostics.Append(resp.State.Set(ctx, streamConnectionState)...)
+		return
+	}
+
 	connV2 := r.Client.AtlasV2
 	projectID := streamConnectionPlan.ProjectID.ValueString()
 	workspaceOrInstanceName := getWorkspaceOrInstanceName(&streamConnectionPlan)