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

norman-zon · rudrakhp · guydc · commit fafa0d12a6b3 · 2026-06-30T18:17:01.000-05:00
* feat: add filterContext field to Lua EnvoyExtensionPolicy (envoyproxy#8715) Add an optional `filterContext` field (map[string]string) to the Lua type in EnvoyExtensionPolicySpec. This exposes Envoy's existing LuaPerRoute.filter_context so that a shared Lua script can be parameterized differently per route via request_handle:filterContext(). Without this, users must either duplicate the entire script inline with hardcoded values or resort to EnvoyPatchPolicy to manually patch xDS. Changes: - api: add FilterContext to Lua struct - ir: add FilterContext to IR Lua struct - gatewayapi: pass FilterContext from API to IR in buildLua() - xds: set FilterContext on LuaPerRoute in patchRoute(), converting map[string]string to structpb.Struct - tests: update gatewayapi/xds translator testdata, add e2e test - docs: add FilterContext section to Lua extension task guide Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * feat: update release notes Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * chore: regenerate test output and helm CRD files Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix: add missing mocks Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): use retry pattern for lua filter context test Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(api): use apiextensionsv1.JSON for Lua filterContext Address review feedback on envoyproxy#8730: - Change FilterContext field type from map[string]string to *apiextensionsv1.JSON in both the API (lua_types.go) and IR (xds.go), matching the existing pattern used by Wasm.Config and DynamicModule.Config. - Drop json/yaml struct tags from ir.Lua.FilterContext, consistent with the other untagged fields on that struct. - Update the xDS translator to unmarshal FilterContext.Raw into structpb.Struct via protojson.Unmarshal, replacing the previous string-only map iteration. - Regenerate deepcopy, CRD manifests, and test fixtures. Users can now pass non-string JSON values (numbers, bools, nested objects) in filterContext without stringifying them. Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): use request_handle:filterContext() and dynamicMetadata to propagate filter context in Lua test filterContext() is only available on request_handle, not response_handle. Read the value in envoy_on_request and store it via dynamicMetadata, then retrieve it in envoy_on_response to set the X-Lua-Filter-Context header. Fixes TestE2E/LuaHTTP/http_route_with_lua_filter_context Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): simplify lua filter context script to use response_handle:filterContext() directly The previous script had a nil-value bug: - ctx["custom_value"] returns nil when filterContext() wraps an empty struct - Storing nil via dynamicMetadata and then using it in headers():add() caused a silent Lua error, so the response header was never set Fix by calling response_handle:filterContext() directly in envoy_on_response, which is available on both request and response handles per Envoy's C++ source. Also add a nil guard for val before calling headers():add() to be safe. Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): use dynamicMetadata to bridge lua filter context between phases Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): simplify lua filter context by storing value string directly Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> * fix(e2e): read Lua filterContext via ctx:get() instead of table indexing filterContext() returns a MetadataMapWrapper whose only Lua methods are get and __pairs; its metatable __index points at the methods table, so ctx["custom_value"] resolves to a method lookup and always returns nil. Read values via ctx:get("custom_value") instead. The per-route filter config is re-resolved on the response path, so the response handle exposes filterContext directly; the dynamicMetadata bridge is unnecessary and the script is now a single response-phase function. Update the luavalidator mock so StreamHandle:filterContext() returns the Metadata wrapper (with a :get method) matching real Envoy, add a validator test for the get() syntax, and fix the docs examples accordingly. Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> --------- Signed-off-by: Norman Stetter <85173861+norman-zon@users.noreply.github.com> Signed-off-by: Rudrakh Panigrahi <rudrakh97@gmail.com> Co-authored-by: Rudrakh Panigrahi <rudrakh97@gmail.com>
diff --git a/api/v1alpha1/lua_types.go b/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"`
 }
diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/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
diff --git a/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/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
diff --git a/internal/gatewayapi/envoyextensionpolicy.go b/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
 }
 
diff --git a/internal/gatewayapi/luavalidator/lua_validator_test.go b/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) {
diff --git a/internal/gatewayapi/luavalidator/mocks.lua b/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
 
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua-validation-disabled.out.yaml b/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
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua-validation-syntax.out.yaml b/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
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-invalid-lua.out.yaml b/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
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-lua-configmap.in.yaml b/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:
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-lua-configmap.out.yaml b/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
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-lua.in.yaml b/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
diff --git a/internal/gatewayapi/testdata/envoyextensionpolicy-with-lua.out.yaml b/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
diff --git a/internal/ir/xds.go b/internal/ir/xds.go
@@ -3735,6 +3735,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.
diff --git a/internal/ir/zz_generated.deepcopy.go b/internal/ir/zz_generated.deepcopy.go
diff --git a/internal/xds/translator/lua.go b/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
diff --git a/internal/xds/translator/testdata/in/xds-ir/lua.yaml b/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:
diff --git a/internal/xds/translator/testdata/out/xds-ir/lua.routes.yaml b/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
diff --git a/release-notes/current.yaml b/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.
 
diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -4124,6 +4124,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
diff --git a/site/content/en/latest/tasks/extensibility/lua.md b/site/content/en/latest/tasks/extensibility/lua.md
diff --git a/test/e2e/testdata/lua-http.yaml b/test/e2e/testdata/lua-http.yaml
diff --git a/test/e2e/tests/lua_http.go b/test/e2e/tests/lua_http.go
diff --git a/test/helm/gateway-crds-helm/all.out.yaml b/test/helm/gateway-crds-helm/all.out.yaml
diff --git a/test/helm/gateway-crds-helm/e2e.out.yaml b/test/helm/gateway-crds-helm/e2e.out.yaml
diff --git a/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml b/test/helm/gateway-crds-helm/envoy-gateway-crds.out.yaml

Original file line number	Diff line number	Diff line change
`@@ -774,8 +774,9 @@ func (t *Translator) buildLua(`
`774`	`774`	`return nil, fmt.Errorf("validation failed for lua body in policy with name %v: %w", name, err)`
`775`	`775`	`}`
`776`	`776`	`return &ir.Lua{`
`777`		`- Name: name,`
`778`		`- Code: luaCode,`
	`777`	`+ Name: name,`
	`778`	`+ Code: luaCode,`
	`779`	`+ FilterContext: lua.FilterContext,`
`779`	`780`	`}, nil`
`780`	`781`	`}`
`781`	`782`