performance: opt-in debounce for the provider reconcile (#9803)

* add opt-in debounce for the provider reconcile

Every watch in the gatewayapi controller enqueues the same GatewayClass
request, so the workqueue already collapses events that arrive while a
reconcile is in flight: the request sits in the dirty set and is requeued
exactly once when Done is called. What the workqueue does not do is wait.
When a reconcile is fast relative to the event rate the queue drains
between events, and each event then costs a full rebuild of the resource
tree even though only the resulting state matters.

Wrap the controller's workqueue so that Add is held until no new request
has arrived for debounce.after, bounded by debounce.max so that sustained
churn cannot defer a reconcile indefinitely. AddAfter and AddRateLimited
reach the embedded queue directly, so error backoff is never delayed.

Reuses the same top-level debounce field in the EnvoyGateway config, and
is disabled by default. Note that status is computed during reconcile, so
enabling this also delays status updates by up to debounce.max.

Signed-off-by: Huabing (Robin) Zhao <zhaohuabing@gmail.com>
Signed-off-by: Huabing (Robin) Zhao <huabing@tetrate.io>

* test: run conformance and e2e with debounce enabled

Add a debounce profile that turns on reconcile debouncing at the shipped
defaults, and a conformance and an e2e matrix entry that run against it,
so holding a burst of resource changes before reconciling is covered by
the existing suites rather than only by unit tests.

Conformance configures Envoy Gateway from the helm values profile, while
e2e additionally applies the envoy-gateway-config ConfigMap, so both
files are needed for the profile to take effect in both suites.

Signed-off-by: Huabing (Robin) Zhao <zhaohuabing@gmail.com>
Signed-off-by: Huabing (Robin) Zhao <huabing@tetrate.io>

* address comments

Signed-off-by: Huabing (Robin) Zhao <huabing@tetrate.io>

---------

Signed-off-by: Huabing (Robin) Zhao <zhaohuabing@gmail.com>
Signed-off-by: Huabing (Robin) Zhao <huabing@tetrate.io>

Author: zhaohuabing

.github/workflows/build_and_test.yaml

@@ -202,6 +202,10 @@ jobs:
           ipFamily: ipv4
           profile: merge-backends
           gwapiChannel: experimental
+        - version: v1.36.1
+          ipFamily: ipv4
+          profile: debounce
+          gwapiChannel: experimental
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
     - uses: ./tools/github-actions/setup-deps
@@ -273,6 +277,9 @@ jobs:
         - version: v1.36.1
           ipFamily: ipv4
           profile: watch-namespaces
+        - version: v1.36.1
+          ipFamily: ipv4
+          profile: debounce
 
     steps:
     - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

api/v1alpha1/envoygateway_helpers.go

@@ -6,8 +6,10 @@
 package v1alpha1
 
 import (
+	"fmt"
 	"net"
 	"strconv"
+	"time"
 
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/utils/ptr"
@@ -239,6 +241,52 @@ func DefaultXDSServer() *XDSServer {
 	return &XDSServer{}
 }
 
+const (
+	// DefaultDebounceAfter is the default quiet period before a pending batch of
+	// resource changes is flushed.
+	DefaultDebounceAfter = 100 * time.Millisecond
+
+	// DefaultDebounceMax is the default upper bound on how long a resource change
+	// may be held before a flush is forced.
+	DefaultDebounceMax = 10 * time.Second
+)
+
+// Enabled reports whether debouncing of resource changes is turned on. Debouncing
+// is opt in, so defining the config is what turns it on.
+func (d *Debounce) Enabled() bool {
+	return d != nil
+}
+
+// ResolveDurations returns the quiet period and the maximum hold time, substituting
+// the defaults for any field left unset. It is the single place these fields are
+// parsed, so every consumer agrees on what a given configuration means.
+func (d *Debounce) ResolveDurations() (after, maxHold time.Duration, err error) {
+	after, maxHold = DefaultDebounceAfter, DefaultDebounceMax
+	if d == nil {
+		return after, maxHold, nil
+	}
+
+	if d.After != nil {
+		if after, err = time.ParseDuration(string(*d.After)); err != nil {
+			return 0, 0, fmt.Errorf("invalid debounce.after: %w", err)
+		}
+		if after <= 0 {
+			return 0, 0, fmt.Errorf("debounce.after must be greater than zero")
+		}
+	}
+
+	if d.Max != nil {
+		if maxHold, err = time.ParseDuration(string(*d.Max)); err != nil {
+			return 0, 0, fmt.Errorf("invalid debounce.max: %w", err)
+		}
+		if maxHold <= 0 {
+			return 0, 0, fmt.Errorf("debounce.max must be greater than zero")
+		}
+	}
+
+	return after, maxHold, nil
+}
+
 // DefaultEnvoyGatewayLogging returns a new EnvoyGatewayLogging with default configuration parameters.
 func DefaultEnvoyGatewayLogging() *EnvoyGatewayLogging {
 	return &EnvoyGatewayLogging{

api/v1alpha1/envoygateway_helpers_test.go

@@ -9,6 +9,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestIsRunningOnKubernetes(t *testing.T) {
@@ -430,3 +431,20 @@ func TestGetKubernetesInfrastructureConfiguration(t *testing.T) {
 		})
 	}
 }
+
+func TestDebounceDefaultsToDisabled(t *testing.T) {
+	eg := &EnvoyGateway{}
+	eg.SetEnvoyGatewayDefaults()
+
+	// Debouncing is opt in, so defaulting must not define the config, and defining
+	// it is what turns debouncing on.
+	require.Nil(t, eg.Debounce)
+	require.False(t, eg.Debounce.Enabled())
+	require.True(t, (&Debounce{}).Enabled())
+
+	// A config that sets no durations falls back to the advertised defaults.
+	after, maxHold, err := (&Debounce{}).ResolveDurations()
+	require.NoError(t, err)
+	require.Equal(t, DefaultDebounceAfter, after)
+	require.Equal(t, DefaultDebounceMax, maxHold)
+}

api/v1alpha1/envoygateway_types.go

@@ -82,6 +82,14 @@ type EnvoyGatewaySpec struct {
 	// +optional
 	XDSServer *XDSServer `json:"xdsServer,omitempty"`
 
+	// Debounce defines how Envoy Gateway coalesces bursts of resource changes
+	// before reconciling them into new configuration for Envoy Proxy.
+	// If unspecified, debouncing is disabled and every change is reconciled on
+	// its own. Applies to the Kubernetes provider only.
+	//
+	// +optional
+	Debounce *Debounce `json:"debounce,omitempty"`
+
 	// RateLimit defines the configuration associated with the Rate Limit service
 	// deployed by Envoy Gateway required to implement the Global Rate limiting
 	// functionality. The specific rate limit service used here is the reference
@@ -246,6 +254,46 @@ type XDSServer struct {
 	MaxReceiveMessageSize *resource.Quantity `json:"maxReceiveMessageSize,omitempty"`
 }
 
+// Debounce defines how Envoy Gateway coalesces bursts of resource changes before
+// reconciling them into new configuration for Envoy Proxy.
+//
+// Without debouncing, each resource change costs a full reconcile, so a burst of
+// changes rebuilds the resource tree, retranslates and pushes once per change even
+// though only the resulting state matters. That spends control plane CPU on work that
+// is immediately superseded, and makes the proxies apply configuration that will be
+// replaced moments later.
+//
+// Debouncing merges changes that arrive close together into a single reconcile, so the
+// cost of a burst approaches that of a single change. The tradeoff is that propagation
+// of a change, and of the status derived from it, may be delayed by up to Max.
+//
+// Debouncing is opt in: it is on whenever this field is set, and off when it is
+// left unset.
+//
+// This applies to the Kubernetes provider only. It has no effect when the resource
+// provider is File, whose reconcile loop is driven directly by file change events.
+type Debounce struct {
+	// After is the quiet period. A pending batch of changes is flushed once no new
+	// change has arrived for this duration, so isolated changes still propagate
+	// promptly.
+	//
+	// If unspecified, defaults to 100ms.
+	//
+	// +optional
+	// +kubebuilder:default="100ms"
+	After *gwapiv1.Duration `json:"after,omitempty"`
+
+	// Max bounds how long a change may be held before a flush is forced. Under
+	// sustained churn the quiet period never elapses, so this caps how far behind
+	// the proxies' configuration can fall.
+	//
+	// Must be greater than or equal to After. If unspecified, defaults to 10s.
+	//
+	// +optional
+	// +kubebuilder:default="10s"
+	Max *gwapiv1.Duration `json:"max,omitempty"`
+}
+
 // LeaderElection defines the desired leader election settings.
 type LeaderElection struct {
 	// LeaseDuration defines the time non-leader contenders will wait before attempting to claim leadership.

api/v1alpha1/validation/envoygateway_validate.go

@@ -68,6 +68,10 @@ func ValidateEnvoyGateway(eg *egv1a1.EnvoyGateway) error {
 		return err
 	}
 
+	if err := validateEnvoyGatewayDebounce(eg.Debounce); err != nil {
+		return err
+	}
+
 	if eg.ExtensionAPIs != nil && eg.ExtensionAPIs.DisableLua != nil && *eg.ExtensionAPIs.DisableLua == eg.ExtensionAPIs.EnableLua {
 		return fmt.Errorf("disableLua and enableLua must not have the same value")
 	}
@@ -355,6 +359,23 @@ func validateEnvoyGatewayXDSServer(xdsServer *egv1a1.XDSServer) error {
 	return nil
 }
 
+func validateEnvoyGatewayDebounce(debounce *egv1a1.Debounce) error {
+	if debounce == nil {
+		return nil
+	}
+
+	after, maxHold, err := debounce.ResolveDurations()
+	if err != nil {
+		return err
+	}
+
+	if maxHold < after {
+		return fmt.Errorf("debounce.max (%s) must be greater than or equal to debounce.after (%s)", maxHold, after)
+	}
+
+	return nil
+}
+
 func validateEnvoyGatewayOpenTelemetrySink(sink *egv1a1.EnvoyGatewayOpenTelemetrySink) error {
 	if sink.Protocol != egv1a1.GRPCProtocol && sink.Protocol != egv1a1.HTTPProtocol {
 		return fmt.Errorf("unsupported protocol %s for OpenTelemetry sink, only 'grpc' and 'http' are supported", sink.Protocol)

api/v1alpha1/validation/envoygateway_validate_test.go

@@ -1137,6 +1137,59 @@ func TestValidateEnvoyGatewayXDSServer(t *testing.T) {
 	})
 }
 
+func TestValidateEnvoyGatewayDebounce(t *testing.T) {
+	duration := func(s string) *gwapiv1.Duration {
+		d := gwapiv1.Duration(s)
+		return &d
+	}
+
+	t.Run("valid no overrides", func(t *testing.T) {
+		require.NoError(t, validateEnvoyGatewayDebounce(nil))
+		require.NoError(t, validateEnvoyGatewayDebounce(&egv1a1.Debounce{}))
+	})
+
+	t.Run("valid overrides", func(t *testing.T) {
+		d := &egv1a1.Debounce{After: duration("100ms"), Max: duration("10s")}
+		require.NoError(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("valid equal after and max", func(t *testing.T) {
+		d := &egv1a1.Debounce{After: duration("1s"), Max: duration("1s")}
+		require.NoError(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("invalid after duration", func(t *testing.T) {
+		d := &egv1a1.Debounce{After: duration("bad")}
+		require.Error(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("invalid max duration", func(t *testing.T) {
+		d := &egv1a1.Debounce{Max: duration("bad")}
+		require.Error(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("non positive after", func(t *testing.T) {
+		d := &egv1a1.Debounce{After: duration("0s")}
+		require.Error(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("non positive max", func(t *testing.T) {
+		d := &egv1a1.Debounce{Max: duration("-1s")}
+		require.Error(t, validateEnvoyGatewayDebounce(d))
+	})
+
+	t.Run("max shorter than after", func(t *testing.T) {
+		d := &egv1a1.Debounce{After: duration("5s"), Max: duration("1s")}
+		require.ErrorContains(t, validateEnvoyGatewayDebounce(d), "must be greater than or equal to")
+	})
+
+	t.Run("max shorter than defaulted after", func(t *testing.T) {
+		// After falls back to its 100ms default, so a 10ms max is invalid.
+		d := &egv1a1.Debounce{Max: duration("10ms")}
+		require.Error(t, validateEnvoyGatewayDebounce(d))
+	})
+}
+
 func TestDefaultEnvoyGatewayLoggingLevel(t *testing.T) {
 	type args struct {
 		component string

api/v1alpha1/zz_generated.deepcopy.go

@@ -187,17 +187,31 @@ func newGatewayAPIController(ctx context.Context, mgr manager.Manager, cfg *conf
 		r.client = newNamespaceSelectorClient(r.client, r.namespaceLabel, cfg.ControllerNamespace)
 	}
 
+	debounce := cfg.EnvoyGateway.Debounce
+	var debounceAfter, debounceMax time.Duration
+	if debounce.Enabled() {
+		var err error
+		if debounceAfter, debounceMax, err = debounce.ResolveDurations(); err != nil {
+			return err
+		}
+		r.log.Info("debouncing reconcile requests", "after", debounceAfter, "max", debounceMax)
+	}
+
 	// controller-runtime doesn't allow run controller with same name for more than once
 	// see https://github.com/kubernetes-sigs/controller-runtime/blob/2b941650bce159006c88bd3ca0d132c7bc40e947/pkg/controller/name.go#L29
 	name := fmt.Sprintf("gatewayapi-%d", time.Now().Unix())
 	c, err := controller.New(name, mgr, controller.Options{
 		Reconciler:         r,
 		SkipNameValidation: skipNameValidation(),
 		NewQueue: func(controllerName string, rateLimiter workqueue.TypedRateLimiter[reconcile.Request]) workqueue.TypedRateLimitingInterface[reconcile.Request] {
-			return workqueue.NewTypedRateLimitingQueueWithConfig(rateLimiter, workqueue.TypedRateLimitingQueueConfig[reconcile.Request]{
+			q := workqueue.NewTypedRateLimitingQueueWithConfig(rateLimiter, workqueue.TypedRateLimitingQueueConfig[reconcile.Request]{
 				Name:            controllerName,
 				MetricsProvider: workqueuemetrics.WorkqueueMetricsProvider{},
 			})
+			if !debounce.Enabled() {
+				return q
+			}
+			return newDebouncingQueue(q, debounceAfter, debounceMax)
 		},
 	})
 	if err != nil {