Add EqualAppServers

api/types/appserver.go

@@ -17,8 +17,10 @@ limitations under the License.
 package types
 
 import (
+	"context"
 	"fmt"
 	"iter"
+	"log/slog"
 	"slices"
 	"sort"
 	"time"
@@ -28,6 +30,7 @@ import (
 	"github.com/gravitational/teleport/api"
 	"github.com/gravitational/teleport/api/constants"
 	componentfeaturesv1 "github.com/gravitational/teleport/api/gen/proto/go/teleport/componentfeatures/v1"
+	"github.com/gravitational/teleport/api/types/appserveropts"
 	"github.com/gravitational/teleport/api/utils"
 	"github.com/gravitational/teleport/api/utils/iterutils"
 )
@@ -357,11 +360,15 @@ func (s *AppServerV3) SetStaticLabels(sl map[string]string) {
 
 // Copy returns a copy of this app server object.
 func (s *AppServerV3) Copy() AppServer {
-	return utils.CloneProtoMsg(s)
+	return s.copy()
 }
 
 func (s *AppServerV3) CloneResource() ResourceWithLabels {
-	return s.Copy()
+	return s.copy()
+}
+
+func (s *AppServerV3) copy() *AppServerV3 {
+	return utils.CloneProtoMsg(s)
 }
 
 // MatchSearch goes through select field values and tries to
@@ -463,3 +470,35 @@ func (s AppServers) Applications() iter.Seq[Application] {
 		return appServer.GetApp()
 	}, slices.Values(s))
 }
+
+// EqualAppServers checks equality to another AppServer. Some options may cause the other to be
+// copied. Please refer to the options documentation.
+func EqualAppServers(a, b AppServer, opts ...appserveropts.EqualOpt) bool {
+	aV3, ok := a.(*AppServerV3)
+	if !ok {
+		slog.ErrorContext(context.Background(), "AppServer a passed to EqualAppServers must be of type *AppServerV3 (this is a bug)", "actual_type", fmt.Sprintf("%T", a))
+		return false
+	}
+	bV3, ok := b.(*AppServerV3)
+	if !ok {
+		slog.ErrorContext(context.Background(), "AppServer b passed to EqualAppServers must be of type *AppServerV3 (this is a bug)", "actual_type", fmt.Sprintf("%T", b))
+		return false
+	}
+
+	opt := appserveropts.NewEqual(opts)
+
+	needsClone := !opt.SkipClone && opt.IgnoreHostID
+	if needsClone {
+		// We could avoid one clone by setting value of one to the other but it's probably
+		// better to explicitly zero ignored values in both to catch potential bugs early.
+		aV3 = aV3.copy()
+		bV3 = bV3.copy()
+	}
+
+	if opt.IgnoreHostID {
+		aV3.Spec.HostID = ""
+		bV3.Spec.HostID = ""
+	}
+
+	return deriveTeleportEqualAppServer(aV3, bV3)
+}

api/types/appserver_test.go

@@ -19,9 +19,12 @@ package types
 import (
 	"testing"
 
+	"github.com/google/go-cmp/cmp"
 	"github.com/stretchr/testify/require"
 
 	"github.com/gravitational/teleport/api"
+	"github.com/gravitational/teleport/api/types/appserveropts"
+	"github.com/gravitational/teleport/api/types/internal/equaltesting"
 )
 
 func TestGetTunnelType(t *testing.T) {
@@ -120,3 +123,58 @@ func TestNewAppServerForAWSOIDCIntegration(t *testing.T) {
 		})
 	}
 }
+
+func Test_AppServer_IsEqualOpt(t *testing.T) {
+	t.Parallel()
+
+	filled := &AppServerV3{}
+	err := equaltesting.FillValue(
+		filled,
+		equaltesting.WithIgnoreUnexported(true),
+		equaltesting.WithSkipProtoXXXFields(true),
+	)
+	require.NoError(t, err)
+
+	// Check basic equality.
+	{
+		a, b := filled.copy(), filled.copy()
+
+		require.Empty(t, cmp.Diff(a, b))
+		require.True(t, EqualAppServers(a, b))
+	}
+
+	// Check returns false for non-AppServerV3 type.
+	{
+		var dummy AppServer
+		require.False(t, EqualAppServers(filled, dummy))
+		require.False(t, EqualAppServers(dummy, filled))
+		require.False(t, EqualAppServers(dummy, dummy))
+	}
+
+	// Check WithIgnoreHostID.
+	{
+		a, b := filled.copy(), filled.copy()
+		const aHostID, bHostID = "a_host_id", "b_host_id"
+		a.Spec.HostID = aHostID
+		b.Spec.HostID = bHostID
+
+		require.False(t, EqualAppServers(a, b))
+		require.True(t, EqualAppServers(a, b, appserveropts.WithIgnoreHostID(true)))
+
+		// Make sure there are no overwrites for the HostID
+		require.NotEqual(t, a.Spec.HostID, b.Spec.HostID)
+		require.Equal(t, aHostID, a.Spec.HostID)
+		require.Equal(t, bHostID, b.Spec.HostID)
+
+		// Let's check WithSkipClone
+		require.True(t, EqualAppServers(
+			a, b,
+			appserveropts.WithIgnoreHostID(true),
+			appserveropts.WithSkipClone(true)),
+		)
+
+		// This time HostID is overwritten because we skipped cloning.
+		require.Empty(t, a.Spec.HostID)
+		require.Empty(t, b.Spec.HostID)
+	}
+}

api/types/appserveropts/app_server_opts.go

@@ -0,0 +1,50 @@
+// Copyright 2026 Gravitational, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package appserveropts
+
+type EqualOptions struct {
+	SkipClone    bool
+	IgnoreHostID bool
+}
+
+func NewEqual(opts []EqualOpt) EqualOptions {
+	opt := EqualOptions{}
+	for _, o := range opts {
+		o(&opt)
+	}
+	return opt
+}
+
+type EqualOpt func(*EqualOptions)
+
+// WithSkipClone configures EqualAppServers to skip cloning and directly mutate the input app
+// servers if necessary. Use this option only when you're certain the input app servers can be
+// safely modified (e.g., they're already clones or will be discarded after comparison).
+func WithSkipClone(skipClone bool) EqualOpt {
+	return func(c *EqualOptions) {
+		c.SkipClone = skipClone
+	}
+}
+
+// WithIgnoreHostID when set to true forces to ignore differences in Spec.HostID while checking
+// AppServer equality.
+//
+// NOTE: When specified the app servers passed to the EqualAppServers will be cloned. To avoid that
+// [WithSkipClone] can be passed.
+func WithIgnoreHostID(ignoreHostID bool) EqualOpt {
+	return func(o *EqualOptions) {
+		o.IgnoreHostID = ignoreHostID
+	}
+}