fix: custom response should be put at the first of the filter chain

api/v1alpha1/envoyproxy_types.go

@@ -102,12 +102,16 @@ type EnvoyProxySpec struct {
 	// If unspecified, the default filter order is applied.
 	// Default filter order is:
 	//
+	// - envoy.filters.http.custom_response
+	//
 	// - envoy.filters.http.health_check
 	//
 	// - envoy.filters.http.fault
 	//
 	// - envoy.filters.http.cors
 	//
+	// - envoy.filters.http.header_mutation
+	//
 	// - envoy.filters.http.ext_authz
 	//
 	// - envoy.filters.http.api_key_auth
@@ -138,8 +142,6 @@ type EnvoyProxySpec struct {
 	//
 	// - envoy.filters.http.grpc_stats
 	//
-	// - envoy.filters.http.custom_response
-	//
 	// - envoy.filters.http.credential_injector
 	//
 	// - envoy.filters.http.compressor
@@ -246,10 +248,13 @@ type FilterPosition struct {
 }
 
 // EnvoyFilter defines the type of Envoy HTTP filter.
-// +kubebuilder:validation:Enum=envoy.filters.http.health_check;envoy.filters.http.fault;envoy.filters.http.cors;envoy.filters.http.ext_authz;envoy.filters.http.api_key_auth;envoy.filters.http.basic_auth;envoy.filters.http.oauth2;envoy.filters.http.jwt_authn;envoy.filters.http.stateful_session;envoy.filters.http.buffer;envoy.filters.http.lua;envoy.filters.http.ext_proc;envoy.filters.http.wasm;envoy.filters.http.rbac;envoy.filters.http.local_ratelimit;envoy.filters.http.ratelimit;envoy.filters.http.grpc_web;envoy.filters.http.grpc_stats;envoy.filters.http.custom_response;envoy.filters.http.credential_injector;envoy.filters.http.compressor;envoy.filters.http.dynamic_forward_proxy
+// +kubebuilder:validation:Enum=envoy.filters.http.custom_response;envoy.filters.http.health_check;envoy.filters.http.fault;envoy.filters.http.cors;envoy.filters.http.header_mutation;envoy.filters.http.ext_authz;envoy.filters.http.api_key_auth;envoy.filters.http.basic_auth;envoy.filters.http.oauth2;envoy.filters.http.jwt_authn;envoy.filters.http.stateful_session;envoy.filters.http.buffer;envoy.filters.http.lua;envoy.filters.http.ext_proc;envoy.filters.http.wasm;envoy.filters.http.rbac;envoy.filters.http.local_ratelimit;envoy.filters.http.ratelimit;envoy.filters.http.grpc_web;envoy.filters.http.grpc_stats;envoy.filters.http.credential_injector;envoy.filters.http.compressor;envoy.filters.http.dynamic_forward_proxy
 type EnvoyFilter string
 
 const (
+	// EnvoyFilterCustomResponse defines the Envoy HTTP custom response filter.
+	EnvoyFilterCustomResponse EnvoyFilter = "envoy.filters.http.custom_response"
+
 	// EnvoyFilterHealthCheck defines the Envoy HTTP health check filter.
 	EnvoyFilterHealthCheck EnvoyFilter = "envoy.filters.http.health_check"
 
@@ -259,6 +264,9 @@ const (
 	// EnvoyFilterCORS defines the Envoy HTTP CORS filter.
 	EnvoyFilterCORS EnvoyFilter = "envoy.filters.http.cors"
 
+	// EnvoyFilterHeaderMutation defines the Envoy HTTP header mutation filter
+	EnvoyFilterHeaderMutation EnvoyFilter = "envoy.filters.http.header_mutation"
+
 	// EnvoyFilterExtAuthz defines the Envoy HTTP external authorization filter.
 	EnvoyFilterExtAuthz EnvoyFilter = "envoy.filters.http.ext_authz"
 
@@ -278,15 +286,18 @@ const (
 	// EnvoyFilterSessionPersistence defines the Envoy HTTP session persistence filter.
 	EnvoyFilterSessionPersistence EnvoyFilter = "envoy.filters.http.stateful_session"
 
+	// EnvoyFilterBuffer defines the Envoy HTTP buffer filter
+	EnvoyFilterBuffer EnvoyFilter = "envoy.filters.http.buffer"
+
+	// EnvoyFilterLua defines the Envoy HTTP Lua filter.
+	EnvoyFilterLua EnvoyFilter = "envoy.filters.http.lua"
+
 	// EnvoyFilterExtProc defines the Envoy HTTP external process filter.
 	EnvoyFilterExtProc EnvoyFilter = "envoy.filters.http.ext_proc"
 
 	// EnvoyFilterWasm defines the Envoy HTTP WebAssembly filter.
 	EnvoyFilterWasm EnvoyFilter = "envoy.filters.http.wasm"
 
-	// EnvoyFilterLua defines the Envoy HTTP Lua filter.
-	EnvoyFilterLua EnvoyFilter = "envoy.filters.http.lua"
-
 	// EnvoyFilterRBAC defines the Envoy RBAC filter.
 	EnvoyFilterRBAC EnvoyFilter = "envoy.filters.http.rbac"
 
@@ -302,9 +313,6 @@ const (
 	// EnvoyFilterGRPCStats defines the Envoy HTTP gRPC stats filter.
 	EnvoyFilterGRPCStats EnvoyFilter = "envoy.filters.http.grpc_stats"
 
-	// EnvoyFilterCustomResponse defines the Envoy HTTP custom response filter.
-	EnvoyFilterCustomResponse EnvoyFilter = "envoy.filters.http.custom_response"
-
 	// EnvoyFilterCredentialInjector defines the Envoy HTTP credential injector filter.
 	EnvoyFilterCredentialInjector EnvoyFilter = "envoy.filters.http.credential_injector"
 
@@ -317,12 +325,6 @@ const (
 	// EnvoyFilterRouter defines the Envoy HTTP router filter.
 	EnvoyFilterRouter EnvoyFilter = "envoy.filters.http.router"
 
-	// EnvoyFilterBuffer defines the Envoy HTTP buffer filter
-	EnvoyFilterBuffer EnvoyFilter = "envoy.filters.http.buffer"
-
-	// EnvoyFilterHeaderMutation defines the Envoy HTTP header mutation filter
-	EnvoyFilterHeaderMutation EnvoyFilter = "envoy.filters.http.header_mutation"
-
 	// StatFormatterRouteName defines the Route Name formatter for stats
 	StatFormatterRouteName string = "%ROUTE_NAME%"
 

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

@@ -284,12 +284,16 @@ spec:
                   If unspecified, the default filter order is applied.
                   Default filter order is:
 
+                  - envoy.filters.http.custom_response
+
                   - envoy.filters.http.health_check
 
                   - envoy.filters.http.fault
 
                   - envoy.filters.http.cors
 
+                  - envoy.filters.http.header_mutation
+
                   - envoy.filters.http.ext_authz
 
                   - envoy.filters.http.api_key_auth
@@ -320,8 +324,6 @@ spec:
 
                   - envoy.filters.http.grpc_stats
 
-                  - envoy.filters.http.custom_response
-
                   - envoy.filters.http.credential_injector
 
                   - envoy.filters.http.compressor
@@ -340,9 +342,11 @@ spec:
                         After defines the filter that should come after the filter.
                         Only one of Before or After must be set.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -358,7 +362,6 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy
@@ -368,9 +371,11 @@ spec:
                         Before defines the filter that should come before the filter.
                         Only one of Before or After must be set.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -386,17 +391,18 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy
                       type: string
                     name:
                       description: Name of the filter.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -412,7 +418,6 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy

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

@@ -283,12 +283,16 @@ spec:
                   If unspecified, the default filter order is applied.
                   Default filter order is:
 
+                  - envoy.filters.http.custom_response
+
                   - envoy.filters.http.health_check
 
                   - envoy.filters.http.fault
 
                   - envoy.filters.http.cors
 
+                  - envoy.filters.http.header_mutation
+
                   - envoy.filters.http.ext_authz
 
                   - envoy.filters.http.api_key_auth
@@ -319,8 +323,6 @@ spec:
 
                   - envoy.filters.http.grpc_stats
 
-                  - envoy.filters.http.custom_response
-
                   - envoy.filters.http.credential_injector
 
                   - envoy.filters.http.compressor
@@ -339,9 +341,11 @@ spec:
                         After defines the filter that should come after the filter.
                         Only one of Before or After must be set.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -357,7 +361,6 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy
@@ -367,9 +370,11 @@ spec:
                         Before defines the filter that should come before the filter.
                         Only one of Before or After must be set.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -385,17 +390,18 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy
                       type: string
                     name:
                       description: Name of the filter.
                       enum:
+                      - envoy.filters.http.custom_response
                       - envoy.filters.http.health_check
                       - envoy.filters.http.fault
                       - envoy.filters.http.cors
+                      - envoy.filters.http.header_mutation
                       - envoy.filters.http.ext_authz
                       - envoy.filters.http.api_key_auth
                       - envoy.filters.http.basic_auth
@@ -411,7 +417,6 @@ spec:
                       - envoy.filters.http.ratelimit
                       - envoy.filters.http.grpc_web
                       - envoy.filters.http.grpc_stats
-                      - envoy.filters.http.custom_response
                       - envoy.filters.http.credential_injector
                       - envoy.filters.http.compressor
                       - envoy.filters.http.dynamic_forward_proxy

internal/xds/translator/httpfilters.go

@@ -76,15 +76,15 @@ type OrderedHTTPFilters []*OrderedHTTPFilter
 
 // newOrderedHTTPFilter gives each HTTP filter a rational order.
 // This is needed because the order of the filters is important.
-// For example, the health_check filter should be placed in the first position because external load
-// balancer determines whether envoy should receive traffic based on the health check result which
-// only depending on the current draining state of the envoy, result should not be affected by other
-// filters, or else user traffic disruption may happen.
-// the fault filter should be placed in the second position because
-// it doesn't rely on the functionality of other filters, and rejecting early can save computation costs
-// for the remaining filters, the cors filter should be put at the third to avoid unnecessary
-// processing of other filters for unauthorized cross-region access.
-// The router filter must be the last one since it's a terminal filter.
+// For example:
+//   - the custom_response filter should be placed first to ensure it sees local replies.
+//   - the health_check filter should be placed next because external load balancer determines whether envoy should
+//     receive traffic based on the health check result which only depending on the current draining state of the envoy,
+//     result should not be affected by other filters, or else user traffic disruption may happen.
+//   - the fault filter should be placed after it because it doesn't rely on the functionality of other filters,
+//     and rejecting early can save computation costs for the remaining filters.
+//   - the cors filter should be put after that to avoid unnecessary processing of other filters for unauthorized cross-region access.
+//   - the router filter must be the last one since it's a terminal filter.
 //
 // Important: please modify this method and set the order for the new filter
 // when adding a new filter in the HCM filter chain.
@@ -98,31 +98,33 @@ func newOrderedHTTPFilter(filter *hcmv3.HttpFilter) *OrderedHTTPFilter {
 	// the remaining filters is skipped when rejected early
 	// Important: After adding new filter types, don't forget to modify the validation rule of the EnvoyFilter type in the API
 	switch {
-	case isFilterType(filter, egv1a1.EnvoyFilterHealthCheck):
+	case isFilterType(filter, egv1a1.EnvoyFilterCustomResponse):
 		order = 0
-	case isFilterType(filter, egv1a1.EnvoyFilterFault):
+	case isFilterType(filter, egv1a1.EnvoyFilterHealthCheck):
 		order = 1
-	case isFilterType(filter, egv1a1.EnvoyFilterCORS):
+	case isFilterType(filter, egv1a1.EnvoyFilterFault):
 		order = 2
+	case isFilterType(filter, egv1a1.EnvoyFilterCORS):
+		order = 3
 	case isFilterType(filter, egv1a1.EnvoyFilterHeaderMutation):
 		// Ensure header mutation run before ext auth which might consume the header.
-		order = 3
-	case isFilterType(filter, egv1a1.EnvoyFilterExtAuthz):
 		order = 4
-	case isFilterType(filter, egv1a1.EnvoyFilterAPIKeyAuth):
+	case isFilterType(filter, egv1a1.EnvoyFilterExtAuthz):
 		order = 5
-	case isFilterType(filter, egv1a1.EnvoyFilterBasicAuth):
+	case isFilterType(filter, egv1a1.EnvoyFilterAPIKeyAuth):
 		order = 6
-	case isFilterType(filter, egv1a1.EnvoyFilterOAuth2):
+	case isFilterType(filter, egv1a1.EnvoyFilterBasicAuth):
 		order = 7
-	case isFilterType(filter, egv1a1.EnvoyFilterJWTAuthn):
+	case isFilterType(filter, egv1a1.EnvoyFilterOAuth2):
 		order = 8
-	case isFilterType(filter, egv1a1.EnvoyFilterSessionPersistence):
+	case isFilterType(filter, egv1a1.EnvoyFilterJWTAuthn):
 		order = 9
-	case isFilterType(filter, egv1a1.EnvoyFilterBuffer):
+	case isFilterType(filter, egv1a1.EnvoyFilterSessionPersistence):
 		order = 10
+	case isFilterType(filter, egv1a1.EnvoyFilterBuffer):
+		order = 11
 	case isFilterType(filter, egv1a1.EnvoyFilterLua):
-		order = 11 + mustGetFilterIndex(filter.Name)
+		order = 12 + mustGetFilterIndex(filter.Name)
 	case isFilterType(filter, egv1a1.EnvoyFilterExtProc):
 		order = 100 + mustGetFilterIndex(filter.Name)
 	case isFilterType(filter, egv1a1.EnvoyFilterWasm):
@@ -137,8 +139,6 @@ func newOrderedHTTPFilter(filter *hcmv3.HttpFilter) *OrderedHTTPFilter {
 		order = 304
 	case isFilterType(filter, egv1a1.EnvoyFilterGRPCStats):
 		order = 305
-	case isFilterType(filter, egv1a1.EnvoyFilterCustomResponse):
-		order = 306
 	case isFilterType(filter, egv1a1.EnvoyFilterCredentialInjector):
 		order = 307
 	case isFilterType(filter, egv1a1.EnvoyFilterCompressor):

internal/xds/translator/httpfilters_test.go

@@ -31,6 +31,7 @@ func Test_sortHTTPFilters(t *testing.T) {
 				httpFilterForTest(egv1a1.EnvoyFilterHeaderMutation),
 				httpFilterForTest(egv1a1.EnvoyFilterJWTAuthn),
 				httpFilterForTest(egv1a1.EnvoyFilterOAuth2 + "/securitypolicy/default/policy-for-http-route-1"),
+				httpFilterForTest(egv1a1.EnvoyFilterCustomResponse),
 				httpFilterForTest(egv1a1.EnvoyFilterBasicAuth),
 				httpFilterForTest(egv1a1.EnvoyFilterWasm + "/envoyextensionpolicy/default/policy-for-http-route-1/2"),
 				httpFilterForTest(egv1a1.EnvoyFilterRateLimit),
@@ -46,6 +47,7 @@ func Test_sortHTTPFilters(t *testing.T) {
 				httpFilterForTest(egv1a1.EnvoyFilterBuffer),
 			},
 			want: []*hcmv3.HttpFilter{
+				httpFilterForTest(egv1a1.EnvoyFilterCustomResponse),
 				httpFilterForTest(wellknown.HealthCheck),
 				httpFilterForTest(egv1a1.EnvoyFilterFault),
 				httpFilterForTest(egv1a1.EnvoyFilterCORS),

release-notes/current.yaml

@@ -8,6 +8,7 @@ breaking changes: |
   Set HTTPRoute Accepted status to False when RequestMirror filter is used together with DirectResponse or RequestRedirect filters.
   Removed Accept-Encoding header from requests to backends when compression is enabled to avoid double compression issues.
   The default value `stats_tags` has been changed to improve the prometheus metrics output. Following metrics are affected: `envoy_cluster_*_rq_time_count`, `envoy_cluster_*_total_match_count`, `envoy_cluster_circuit_breakers_*_cx_open`.
+  Default HTTP filter ordering now places envoy.filters.http.custom_response at the first, which can change the behavior of local replies and header processing.
 
 # Updates addressing vulnerabilities, security flaws, or compliance requirements.
 security updates: |