fix: don't set Deployment replicas when an HPA is configured (#9594)

* fix: don't set Deployment replicas when an HPA is configured

Envoy Gateway applies the proxy and rate limit Deployments with a
server-side apply patch using ForceOwnership, so rendering spec.replicas
made envoy-gateway the owner of that field. Every subsequent
reconciliation then forced the replica count back to the statically
configured value, overriding whatever the HPA had computed.

Omit the replicas field from the rendered Deployment when an HPA is
configured, so Envoy Gateway never claims ownership of spec.replicas and
the HPA is free to scale the Deployment. This is the behavior already
documented for both envoyHpa and rateLimitHpa, but it was never
implemented. Use minReplicas to set a lower bound on the replica count
instead.

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

* docs: add release note

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

* test: regenerate helm CRD golden files

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

---------

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

Author: zhaohuabing

api/v1alpha1/envoyproxy_types.go

@@ -528,6 +528,9 @@ type EnvoyProxyKubernetesProvider struct {
 	EnvoyService *KubernetesServiceSpec `json:"envoyService,omitempty"`
 
 	// EnvoyHpa defines the Horizontal Pod Autoscaler settings for Envoy Proxy Deployment.
+	// If the HPA is set, the Replicas field from EnvoyDeployment will be ignored, and the
+	// number of replicas is solely managed by the HPA. Use MinReplicas to control the
+	// lower bound of the replica count instead.
 	//
 	// +optional
 	EnvoyHpa *KubernetesHorizontalPodAutoscalerSpec `json:"envoyHpa,omitempty"`

charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyproxies.yaml

@@ -10388,8 +10388,11 @@ spec:
                             type: object
                         type: object
                       envoyHpa:
-                        description: EnvoyHpa defines the Horizontal Pod Autoscaler
-                          settings for Envoy Proxy Deployment.
+                        description: |-
+                          EnvoyHpa defines the Horizontal Pod Autoscaler settings for Envoy Proxy Deployment.
+                          If the HPA is set, the Replicas field from EnvoyDeployment will be ignored, and the
+                          number of replicas is solely managed by the HPA. Use MinReplicas to control the
+                          lower bound of the replica count instead.
                         properties:
                           behavior:
                             description: |-

charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml

@@ -10387,8 +10387,11 @@ spec:
                             type: object
                         type: object
                       envoyHpa:
-                        description: EnvoyHpa defines the Horizontal Pod Autoscaler
-                          settings for Envoy Proxy Deployment.
+                        description: |-
+                          EnvoyHpa defines the Horizontal Pod Autoscaler settings for Envoy Proxy Deployment.
+                          If the HPA is set, the Replicas field from EnvoyDeployment will be ignored, and the
+                          number of replicas is solely managed by the HPA. Use MinReplicas to control the
+                          lower bound of the replica count instead.
                         properties:
                           behavior:
                             description: |-

internal/infrastructure/kubernetes/proxy/resource_provider.go

@@ -393,6 +393,15 @@ func (r *ResourceRender) Deployment() (*appsv1.Deployment, error) {
 		return nil, err
 	}
 
+	// When an HPA is configured, the replica count is owned by the HPA, so the replicas
+	// field is left unset here. Since the field is omitted from the server-side apply
+	// patch, Envoy Gateway doesn't take ownership of it and won't revert the replica
+	// count computed by the HPA on subsequent reconciliations.
+	replicas := deploymentConfig.Replicas
+	if provider.GetEnvoyProxyKubeProvider().EnvoyHpa != nil {
+		replicas = nil
+	}
+
 	deployment := &appsv1.Deployment{
 		TypeMeta: metav1.TypeMeta{
 			Kind:       "Deployment",
@@ -405,7 +414,7 @@ func (r *ResourceRender) Deployment() (*appsv1.Deployment, error) {
 			OwnerReferences: r.ownerReferences(),
 		},
 		Spec: appsv1.DeploymentSpec{
-			Replicas: deploymentConfig.Replicas,
+			Replicas: replicas,
 			Strategy: *deploymentConfig.Strategy,
 			// Deployment's selector is immutable.
 			Selector: r.stableSelector(),

internal/infrastructure/kubernetes/proxy/resource_provider_test.go

@@ -200,6 +200,7 @@ func TestDeployment(t *testing.T) {
 		caseName             string
 		infra                *ir.Infra
 		deploy               *egv1a1.KubernetesDeploymentSpec
+		hpa                  *egv1a1.KubernetesHorizontalPodAutoscalerSpec
 		shutdown             *egv1a1.ShutdownConfig
 		shutdownManager      *egv1a1.ShutdownManager
 		proxyLogging         map[egv1a1.ProxyLogComponent]egv1a1.LogLevel
@@ -674,6 +675,21 @@ func TestDeployment(t *testing.T) {
 				Name: new("custom-deployment-name"),
 			},
 		},
+		{
+			// The replicas field must not be rendered when an HPA is configured, so that
+			// Envoy Gateway doesn't own spec.replicas and revert the replica count
+			// computed by the HPA.
+			caseName: "with-hpa",
+			infra:    newTestInfra(),
+			deploy: &egv1a1.KubernetesDeploymentSpec{
+				Replicas: new(int32(2)),
+				Strategy: egv1a1.DefaultKubernetesDeploymentStrategy(),
+			},
+			hpa: &egv1a1.KubernetesHorizontalPodAutoscalerSpec{
+				MinReplicas: new(int32(3)),
+				MaxReplicas: new(int32(10)),
+			},
+		},
 		{
 			caseName:             "gateway-namespace-mode",
 			infra:                newTestInfraWithNamespacedName(types.NamespacedName{Namespace: "ns1", Name: "gateway-1"}),
@@ -693,6 +709,9 @@ func TestDeployment(t *testing.T) {
 			if tc.deploy != nil {
 				kube.EnvoyDeployment = tc.deploy
 			}
+			if tc.hpa != nil {
+				kube.EnvoyHpa = tc.hpa
+			}
 
 			replace := egv1a1.BootstrapTypeReplace
 			if tc.bootstrap != "" {