feat(api): Add filterContext field to Lua type in EnvoyExtensionPolicy

api/v1alpha1/lua_types.go

@@ -5,7 +5,10 @@
 
 package v1alpha1
 
-import gwapiv1 "sigs.k8s.io/gateway-api/apis/v1"
+import (
+	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	gwapiv1 "sigs.k8s.io/gateway-api/apis/v1"
+)
 
 // LuaValueType defines the types of values for Lua supported by Envoy Gateway.
 // +kubebuilder:validation:Enum=Inline;ValueRef
@@ -45,4 +48,11 @@ type Lua struct {
 	// +optional
 	// +unionMember
 	ValueRef *gwapiv1.LocalObjectReference `json:"valueRef,omitempty"`
+	// FilterContext is the filter context configuration for the Lua script.
+	// This must be a JSON object (key/value pairs). The values are made available
+	// to the Lua script via request_handle:filterContext(). This allows a shared
+	// script to be parameterized differently per EnvoyExtensionPolicy/route.
+	//
+	// +optional
+	FilterContext *apiextensionsv1.JSON `json:"filterContext,omitempty"`
 }

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

@@ -1641,6 +1641,13 @@ spec:
                     Lua defines a Lua extension
                     Only one of Inline or ValueRef must be set
                   properties:
+                    filterContext:
+                      description: |-
+                        FilterContext is the filter context configuration for the Lua script.
+                        This must be a JSON object (key/value pairs). The values are made available
+                        to the Lua script via request_handle:filterContext(). This allows a shared
+                        script to be parameterized differently per EnvoyExtensionPolicy/route.
+                      x-kubernetes-preserve-unknown-fields: true
                     inline:
                       description: Inline contains the source code as an inline string.
                       type: string

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

@@ -1640,6 +1640,13 @@ spec:
                     Lua defines a Lua extension
                     Only one of Inline or ValueRef must be set
                   properties:
+                    filterContext:
+                      description: |-
+                        FilterContext is the filter context configuration for the Lua script.
+                        This must be a JSON object (key/value pairs). The values are made available
+                        to the Lua script via request_handle:filterContext(). This allows a shared
+                        script to be parameterized differently per EnvoyExtensionPolicy/route.
+                      x-kubernetes-preserve-unknown-fields: true
                     inline:
                       description: Inline contains the source code as an inline string.
                       type: string

internal/gatewayapi/envoyextensionpolicy.go

@@ -774,8 +774,9 @@ func (t *Translator) buildLua(
 		return nil, fmt.Errorf("validation failed for lua body in policy with name %v: %w", name, err)
 	}
 	return &ir.Lua{
-		Name: name,
-		Code: luaCode,
+		Name:          name,
+		Code:          luaCode,
+		FilterContext: lua.FilterContext,
 	}, nil
 }
 

internal/gatewayapi/luavalidator/lua_validator_test.go

@@ -181,6 +181,19 @@ func Test_BasicValidation(t *testing.T) {
 			},
 			expectedErrSubstring: "",
 		},
+		{
+			name: "stream:filterContext:get",
+			code: `function envoy_on_response(response_handle)
+                     local ctx = response_handle:filterContext()
+                     if ctx ~= nil then
+                       local custom_value = ctx:get("custom_value")
+                       if custom_value ~= nil then
+                         response_handle:headers():add("X-Lua-Filter-Context", custom_value)
+                       end
+                     end
+                   end`,
+			expectedErrSubstring: "",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {

internal/gatewayapi/luavalidator/mocks.lua

@@ -587,6 +587,10 @@ function StreamHandle:connectionStreamInfo()
   return ConnectionStreamInfo
 end
 
+function StreamHandle:filterContext()
+  return Metadata
+end
+
 function StreamHandle:setUpstreamOverrideHost(host, strict)
 end
 

internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua-validation-disabled.out.yaml

@@ -215,6 +215,7 @@ xdsIR:
                   print("Value is greater than 5")
                 end
               end
+            FilterContext: null
             Name: envoyextensionpolicy/default/policy-for-http-route/lua/0
         hostname: www.example.com
         isHTTP2: false

internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua-validation-syntax.out.yaml

@@ -317,6 +317,7 @@ xdsIR:
                   end
                   return envoy.lua.ResponseStatus.Continue
               end
+            FilterContext: null
             Name: envoyextensionpolicy/default/policy-for-http-route/lua/0
         hostname: www.example.com
         isHTTP2: false

internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua.out.yaml

@@ -292,6 +292,7 @@ xdsIR:
           luas:
           - Code: function envoy_on_request(request_handle) request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -327,6 +328,7 @@ xdsIR:
           luas:
           - Code: function envoy_on_request(request_handle) request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false

internal/gatewayapi/testdata/envoyextensionpolicy-with-lua-configmap.in.yaml

@@ -179,6 +179,8 @@ envoyextensionpolicies:
         name: cm-policy-for-http-route
         kind: ConfigMap
         group: v1
+      filterContext:
+        token_header: x-session-token
 - apiVersion: gateway.envoyproxy.io/v1alpha1
   kind: EnvoyExtensionPolicy
   metadata:

internal/gatewayapi/testdata/envoyextensionpolicy-with-lua-configmap.out.yaml

@@ -6,7 +6,9 @@ envoyExtensionPolicies:
     namespace: default
   spec:
     lua:
-    - type: ValueRef
+    - filterContext:
+        token_header: x-session-token
+      type: ValueRef
       valueRef:
         group: v1
         kind: ConfigMap
@@ -464,6 +466,7 @@ xdsIR:
               function envoy_on_request(request_handle)
               request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -503,6 +506,7 @@ xdsIR:
               function envoy_on_request(request_handle)
               request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -542,6 +546,7 @@ xdsIR:
               function envoy_on_request(request_handle)
               request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -579,6 +584,8 @@ xdsIR:
               function envoy_on_response(response_handle)
               response_handle:logWarn('Goodbye.')
               end
+            FilterContext:
+              token_header: x-session-token
             Name: envoyextensionpolicy/default/policy-for-http-route/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -616,6 +623,7 @@ xdsIR:
               function envoy_on_request(request_handle)
               request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false

internal/gatewayapi/testdata/envoyextensionpolicy-with-lua.in.yaml

@@ -85,3 +85,6 @@ envoyextensionpolicies:
       inline: "function envoy_on_response(response_handle)
     response_handle:logWarn('Goodbye.')
     end"
+      filterContext:
+        token_header: x-api-key
+        mode: strict

internal/gatewayapi/testdata/envoyextensionpolicy-with-lua.out.yaml

@@ -7,7 +7,10 @@ envoyExtensionPolicies:
     namespace: default
   spec:
     lua:
-    - inline: function envoy_on_response(response_handle) response_handle:logWarn('Goodbye.')
+    - filterContext:
+        mode: strict
+        token_header: x-api-key
+      inline: function envoy_on_response(response_handle) response_handle:logWarn('Goodbye.')
         end
       type: Inline
     targetRef:
@@ -278,6 +281,9 @@ xdsIR:
           luas:
           - Code: function envoy_on_response(response_handle) response_handle:logWarn('Goodbye.')
               end
+            FilterContext:
+              mode: strict
+              token_header: x-api-key
             Name: envoyextensionpolicy/default/policy-for-http-route/lua/0
         hostname: www.example.com
         isHTTP2: false
@@ -313,6 +319,7 @@ xdsIR:
           luas:
           - Code: function envoy_on_request(request_handle) request_handle:logInfo('Goodbye.')
               end
+            FilterContext: null
             Name: envoyextensionpolicy/envoy-gateway/policy-for-gateway/lua/0
         hostname: www.example.com
         isHTTP2: false

internal/ir/xds.go

@@ -3714,6 +3714,9 @@ type Lua struct {
 	Name string
 	// Code is the Lua source code
 	Code *string
+	// FilterContext is the filter context configuration for the Lua script.
+	// This is a JSON object passed to the Lua script via request_handle:filterContext().
+	FilterContext *apiextensionsv1.JSON
 }
 
 // Wasm holds the information associated with the Wasm extensions.

internal/xds/translator/lua.go

@@ -14,7 +14,9 @@ import (
 	routev3 "github.com/envoyproxy/go-control-plane/envoy/config/route/v3"
 	luafilterv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/lua/v3"
 	hcmv3 "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/network/http_connection_manager/v3"
+	"google.golang.org/protobuf/encoding/protojson"
 	"google.golang.org/protobuf/types/known/anypb"
+	"google.golang.org/protobuf/types/known/structpb"
 
 	egv1a1 "github.com/envoyproxy/gateway/api/v1alpha1"
 	"github.com/envoyproxy/gateway/internal/ir"
@@ -153,6 +155,13 @@ func (*lua) patchRoute(route *routev3.Route, irRoute *ir.HTTPRoute, _ *ir.HTTPLi
 				},
 			},
 		}
+		if ep.FilterContext != nil && ep.FilterContext.Raw != nil {
+			filterCtx := &structpb.Struct{}
+			if err := protojson.Unmarshal(ep.FilterContext.Raw, filterCtx); err != nil {
+				return err
+			}
+			luaPerRoute.FilterContext = filterCtx
+		}
 		luaPerRouteAny, err := anypb.New(luaPerRoute)
 		if err != nil {
 			return err

internal/xds/translator/testdata/in/xds-ir/lua.yaml

@@ -31,6 +31,9 @@ http:
           request_handle:logInfo('Goodbye.')
           end
         name: envoyextensionpolicy/default/policy-for-http-route/lua/0
+        filterContext:
+          token_header: x-api-key
+          mode: strict
   - destination:
       name: httproute/default/httproute-2/rule/0
       settings:

internal/xds/translator/testdata/out/xds-ir/lua.routes.yaml

@@ -15,6 +15,9 @@
       typedPerFilterConfig:
         envoy.filters.http.lua/0:
           '@type': type.googleapis.com/envoy.extensions.filters.http.lua.v3.LuaPerRoute
+          filterContext:
+            mode: strict
+            token_header: x-api-key
           sourceCode:
             inlineString: function envoy_on_request(request_handle) request_handle:logInfo('Goodbye.')
               end

release-notes/current.yaml

@@ -15,6 +15,7 @@ new features: |
   Added a `requestBody` field to the HTTP active health checker in `BackendTrafficPolicy`, allowing a request body payload to be sent during HTTP health checking. The field requires the health check `method` to be `POST` or `PUT`.
   Added a `xdsNACKTotal` metric to track the number of NACKs received from Envoy, labeled by node ID and resource type URL. A NACK is a DiscoveryRequest carrying an ErrorDetail, indicating that Envoy rejected the last config update. This metric can be used to alert on config issues causing xDS rejections.
   Added the `autoSNIFromEndpointHostname` TLS setting to Backends, allowing the SNI value sent to the backend to be automatically derived from the backend endpoint hostname instead of using a fixed SNI value.
+  Added support for `filterContext` field in Lua EnvoyExtensionPolicy, allowing shared Lua scripts to be parameterized per route via `request_handle:filterContext()`.
   Added support for `ListenerSet` as a `targetRef` kind in `ClientTrafficPolicy`, allowing client traffic settings to be applied to a named group of listeners without a gateway-wide policy.
   Added a `fromMetadata` field to global rate limit `limit` in `BackendTrafficPolicy`, allowing the limit value to be sourced from per-request dynamic metadata (e.g. set by an upstream ext_proc), falling back to the static `requests`/`unit` when the metadata is absent.
 

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

@@ -4108,6 +4108,7 @@ _Appears in:_
 | `type` | _[LuaValueType](#luavaluetype)_ |  true  | Inline | Type is the type of method to use to read the Lua value.<br />Valid values are Inline and ValueRef, default is Inline. |
 | `inline` | _string_ |  false  |  | Inline contains the source code as an inline string. |
 | `valueRef` | _[LocalObjectReference](#localobjectreference)_ |  false  |  | ValueRef has the source code specified as a local object reference.<br />Only a reference to ConfigMap is supported.<br />The value of key `lua` in the ConfigMap will be used.<br />If the key is not found, the first value in the ConfigMap will be used. |
+| `filterContext` | _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#json-v1-apiextensions-k8s-io)_ |  false  |  | FilterContext is the filter context configuration for the Lua script.<br />This must be a JSON object (key/value pairs). The values are made available<br />to the Lua script via request_handle:filterContext(). This allows a shared<br />script to be parameterized differently per EnvoyExtensionPolicy/route. |
 
 
 #### LuaValidation