preconnect policy

Signed-off-by: jukie <[email protected]>

Author: jukie

api/v1alpha1/connection_types.go

@@ -70,6 +70,37 @@ type BackendConnection struct {
 	// +optional
 	// +notImplementedHide
 	SocketBufferLimit *resource.Quantity `json:"socketBufferLimit,omitempty"`
+
+	// Preconnect configures proactive upstream connections to reduce latency by establishing
+	// connections before they’re needed and avoiding connection establishment overhead.
+	// If unset, Envoy will fetch connections as needed to serve in-flight requests.
+	//
+	// +optional
+	Preconnect *PreconnectPolicy `json:"preconnect,omitempty"`
+}
+
+// Preconnect configures proactive upstream connections to reduce latency by establishing
+// connections before they’re needed and avoiding connection establishment overhead.
+type PreconnectPolicy struct {
+	// PerUpstreamRatio configures the ratio of connections to anticipate per-upstream for each
+	// incoming connection. This is most effective for high-QPS or latency-sensitive services
+	// where connection establishment cost is significant.
+	// Allowed values are between 1.0 and 3.0.
+	//
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=3
+	// +optional
+	PerUpstreamRatio *float64 `json:"perUpstreamRatio,omitempty"`
+
+	// PredictiveRatio configures how many connections to anticipate for an upstream cluster
+	// for each incoming connection. Useful for latency sensitive, low-QPS services.
+	// Relies on deterministic endpoint selection and is only supported with RoundRobin
+	// or Random load balancing.
+	// Minimum value is 1.0.
+	//
+	// +kubebuilder:validation:Minimum=1
+	// +optional
+	PredictiveRatio *float64 `json:"predictiveRatio,omitempty"`
 }
 
 type ConnectionLimit struct {

api/v1alpha1/shared_types.go

@@ -585,6 +585,8 @@ type BackendCluster struct {
 
 // ClusterSettings provides the various knobs that can be set to control how traffic to a given
 // backend will be configured.
+//
+// +kubebuilder:validation:XValidation:rule="!((has(self.connection) && has(self.connection.preconnect) && has(self.connection.preconnect.predictiveRatio)) && !(has(self.loadBalancer) && has(self.loadBalancer.type) && self.loadBalancer.type in ['Random', 'RoundRobin']))",message="predictiveRatio in preconnect policy only works with RoundRobin or Random load balancers"
 type ClusterSettings struct {
 	// LoadBalancer policy to apply when routing traffic from the gateway to
 	// the backend endpoints. Defaults to `LeastRequest`.

api/v1alpha1/zz_generated.deepcopy.go

@@ -183,6 +183,31 @@ spec:
                       For example, 20Mi, 1Gi, 256Ki etc.
                       Note: that when the suffix is not provided, the value is interpreted as bytes.
                     x-kubernetes-int-or-string: true
+                  preconnect:
+                    description: |-
+                      Preconnect configures proactive upstream connections to reduce latency by establishing
+                      connections before they’re needed and avoiding connection establishment overhead.
+                      If unset, Envoy will fetch connections as needed to serve in-flight requests.
+                    properties:
+                      perUpstreamRatio:
+                        description: |-
+                          PerUpstreamRatio configures the ratio of connections to anticipate per-upstream for each
+                          incoming connection. This is most effective for high-QPS or latency-sensitive services
+                          where connection establishment cost is significant.
+                          Allowed values are between 1.0 and 3.0.
+                        maximum: 3
+                        minimum: 1
+                        type: number
+                      predictiveRatio:
+                        description: |-
+                          PredictiveRatio configures how many connections to anticipate for an upstream cluster
+                          for each incoming connection. Useful for latency sensitive, low-QPS services.
+                          Relies on deterministic endpoint selection and is only supported with RoundRobin
+                          or Random load balancing.
+                          Minimum value is 1.0.
+                        minimum: 1
+                        type: number
+                    type: object
                   socketBufferLimit:
                     allOf:
                     - pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
@@ -2236,6 +2261,12 @@ spec:
                 : true'
             - message: either compression or compressor can be set, not both
               rule: '!has(self.compression) || !has(self.compressor)'
+            - message: predictiveRatio in preconnect policy only works with RoundRobin
+                or Random load balancers
+              rule: '!((has(self.connection) && has(self.connection.preconnect) &&
+                has(self.connection.preconnect.predictiveRatio)) && !(has(self.loadBalancer)
+                && has(self.loadBalancer.type) && self.loadBalancer.type in [''Random'',
+                ''RoundRobin'']))'
           status:
             description: status defines the current status of BackendTrafficPolicy.
             properties:

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

@@ -302,6 +302,31 @@ spec:
                                 For example, 20Mi, 1Gi, 256Ki etc.
                                 Note: that when the suffix is not provided, the value is interpreted as bytes.
                               x-kubernetes-int-or-string: true
+                            preconnect:
+                              description: |-
+                                Preconnect configures proactive upstream connections to reduce latency by establishing
+                                connections before they’re needed and avoiding connection establishment overhead.
+                                If unset, Envoy will fetch connections as needed to serve in-flight requests.
+                              properties:
+                                perUpstreamRatio:
+                                  description: |-
+                                    PerUpstreamRatio configures the ratio of connections to anticipate per-upstream for each
+                                    incoming connection. This is most effective for high-QPS or latency-sensitive services
+                                    where connection establishment cost is significant.
+                                    Allowed values are between 1.0 and 3.0.
+                                  maximum: 3
+                                  minimum: 1
+                                  type: number
+                                predictiveRatio:
+                                  description: |-
+                                    PredictiveRatio configures how many connections to anticipate for an upstream cluster
+                                    for each incoming connection. Useful for latency sensitive, low-QPS services.
+                                    Relies on deterministic endpoint selection and is only supported with RoundRobin
+                                    or Random load balancing.
+                                    Minimum value is 1.0.
+                                  minimum: 1
+                                  type: number
+                              type: object
                             socketBufferLimit:
                               allOf:
                               - pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
@@ -1036,6 +1061,13 @@ spec:
                               type: object
                           type: object
                       type: object
+                      x-kubernetes-validations:
+                      - message: predictiveRatio in preconnect policy only works with
+                          RoundRobin or Random load balancers
+                        rule: '!((has(self.connection) && has(self.connection.preconnect)
+                          && has(self.connection.preconnect.predictiveRatio)) && !(has(self.loadBalancer)
+                          && has(self.loadBalancer.type) && self.loadBalancer.type
+                          in [''Random'', ''RoundRobin'']))'
                     failOpen:
                       default: false
                       description: |-