API: HTTP Filter ordering

api/v1alpha1/envoyproxy_types.go

@@ -86,8 +86,46 @@ type EnvoyProxySpec struct {
 	//
 	// +optional
 	Shutdown *ShutdownConfig `json:"shutdown,omitempty"`
+
+	// FilterOrder defines the order of filters in the Envoy proxy's HTTP filter chain.
+	//
+	// +optional
+	FilterOrder []FilterOrder `json:"filterOrder,omitempty"`
+}
+
+// FilterOrder defines the order of filters in the Envoy proxy's HTTP filter chain.
+// The order of filters is determined by the order field, where the filter with
+// the lowest order value is applied first.
+// If unspecified, the default order of filters is applied.
+// Default order of filters:
+// - envoy.filters.http.cors               0
+// - envoy.filters.http.ext_authz          100
+// - envoy.filters.http.basic_authn        200
+// - envoy.filters.http.oauth2             300
+// - envoy.filters.http.jwt_authn          400
+// - envoy.filters.http.fault              500
+// - envoy.filters.http.local_ratelimit    600
+// - envoy.filters.http.rate_limit         700
+type FilterOrder struct {
+	Filter EnvoyFilter `json:"filter"`
+	Order  uint32      `json:"order"`
 }
 
+// EnvoyFilter defines the type of Envoy HTTP filter.
+// +kubebuilder:validation:Enum=envoy.filters.http.cors;envoy.filters.http.ext_authz;envoy.filters.http.basic_authn;envoy.filters.http.oauth2;envoy.filters.http.jwt_authn;envoy.filters.http.fault;envoy.filters.http.local_ratelimit;envoy.filters.http.rate_limit;envoy.filters.http.routerfilters.http.router
+type EnvoyFilter string
+
+const (
+	EnvoyFilterCORS           EnvoyFilter = "envoy.filters.http.cors"
+	EnvoyFilterExtAuthz       EnvoyFilter = "envoy.filters.http.ext_authz"
+	EnvoyFilterBasicAuthn     EnvoyFilter = "envoy.filters.http.basic_authn"
+	EnvoyFilterOAuth2         EnvoyFilter = "envoy.filters.http.oauth2"
+	EnvoyFilterJWTAuthn       EnvoyFilter = "envoy.filters.http.jwt_authn"
+	EnvoyFilterFault          EnvoyFilter = "envoy.filters.http.fault"
+	EnvoyFilterLocalRateLimit EnvoyFilter = "envoy.filters.http.local_ratelimit"
+	EnvoyFilterRateLimit      EnvoyFilter = "envoy.filters.http.rate_limit"
+)
+
 type ProxyTelemetry struct {
 	// AccessLogs defines accesslog parameters for managed proxies.
 	// If unspecified, will send default format to stdout.

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

@@ -81,6 +81,41 @@ spec:
                 items:
                   type: string
                 type: array
+              filterOrder:
+                description: FilterOrder defines the order of filters in the Envoy
+                  proxy's HTTP filter chain.
+                items:
+                  description: 'FilterOrder defines the order of filters in the Envoy
+                    proxy''s HTTP filter chain. The order of filters is determined
+                    by the order field, where the filter with the lowest order value
+                    is applied first. If unspecified, the default order of filters
+                    is applied. Default order of filters: - envoy.filters.http.cors               0
+                    - envoy.filters.http.ext_authz          100 - envoy.filters.http.basic_authn        200
+                    - envoy.filters.http.oauth2             300 - envoy.filters.http.jwt_authn          400
+                    - envoy.filters.http.fault              500 - envoy.filters.http.local_ratelimit    600
+                    - envoy.filters.http.rate_limit         700'
+                  properties:
+                    filter:
+                      description: EnvoyFilter defines the type of Envoy HTTP filter.
+                      enum:
+                      - envoy.filters.http.cors
+                      - envoy.filters.http.ext_authz
+                      - envoy.filters.http.basic_authn
+                      - envoy.filters.http.oauth2
+                      - envoy.filters.http.jwt_authn
+                      - envoy.filters.http.fault
+                      - envoy.filters.http.local_ratelimit
+                      - envoy.filters.http.rate_limit
+                      - envoy.filters.http.routerfilters.http.router
+                      type: string
+                    order:
+                      format: int32
+                      type: integer
+                  required:
+                  - filter
+                  - order
+                  type: object
+                type: array
               logging:
                 default:
                   level:

site/content/en/latest/api/extension_types.md

@@ -534,6 +534,17 @@ _Appears in:_
 | `priority` | _integer_ |  false  | Priority of the EnvoyExtensionPolicy. If multiple EnvoyExtensionPolices are applied to the same TargetRef, extensions will execute in the ascending order of the priority i.e. int32.min has the highest priority and int32.max has the lowest priority. Defaults to 0. |
 
 
+#### EnvoyFilter
+
+_Underlying type:_ _string_
+
+EnvoyFilter defines the type of Envoy HTTP filter.
+
+_Appears in:_
+- [FilterOrder](#filterorder)
+
+
+
 #### EnvoyGateway
 
 
@@ -957,6 +968,7 @@ _Appears in:_
 | `extraArgs` | _string array_ |  false  | ExtraArgs defines additional command line options that are provided to Envoy. More info: https://www.envoyproxy.io/docs/envoy/latest/operations/cli#command-line-options Note: some command line options are used internally(e.g. --log-level) so they cannot be provided here. |
 | `mergeGateways` | _boolean_ |  false  | MergeGateways defines if Gateway resources should be merged onto the same Envoy Proxy Infrastructure. Setting this field to true would merge all Gateway Listeners under the parent Gateway Class. This means that the port, protocol and hostname tuple must be unique for every listener. If a duplicate listener is detected, the newer listener (based on timestamp) will be rejected and its status will be updated with a "Accepted=False" condition. |
 | `shutdown` | _[ShutdownConfig](#shutdownconfig)_ |  false  | Shutdown defines configuration for graceful envoy shutdown process. |
+| `filterOrder` | _[FilterOrder](#filterorder) array_ |  false  | FilterOrder defines the order of filters in the Envoy proxy's HTTP filter chain. |
 
 
 
@@ -1126,6 +1138,21 @@ _Appears in:_
 | `path` | _string_ |  true  | Path defines the file path used to expose envoy access log(e.g. /dev/stdout). |
 
 
+#### FilterOrder
+
+
+
+FilterOrder defines the order of filters in the Envoy proxy's HTTP filter chain. The order of filters is determined by the order field, where the filter with the lowest order value is applied first. If unspecified, the default order of filters is applied. Default order of filters: - envoy.filters.http.cors               0 - envoy.filters.http.ext_authz          100 - envoy.filters.http.basic_authn        200 - envoy.filters.http.oauth2             300 - envoy.filters.http.jwt_authn          400 - envoy.filters.http.fault              500 - envoy.filters.http.local_ratelimit    600 - envoy.filters.http.rate_limit         700
+
+_Appears in:_
+- [EnvoyProxySpec](#envoyproxyspec)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `envoyFilters` | _[EnvoyFilter](#envoyfilter)_ |  true  |  |
+| `order` | _integer_ |  true  |  |
+
+
 #### GRPCExtAuthService