Skip to content

feat: support SecurityPolicy client-IP authorization for UDPRoute #9833

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zhaohuabing wants to merge 12 commits into
base: main
Choose a base branch
from
Open

feat: support SecurityPolicy client-IP authorization for UDPRoute #9833

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
50633d8
api: allow SecurityPolicy to target UDPRoute
zhaohuabing Aug 25, 2026
f45837c
xds: support client-IP authorization on UDP listeners
zhaohuabing Aug 25, 2026
14b284a
gatewayapi: apply SecurityPolicy authorization to UDP routes
zhaohuabing Aug 25, 2026
e5d3f92
docs: document SecurityPolicy client-IP authorization for UDPRoute
zhaohuabing Aug 25, 2026
136aec0
test: e2e for SecurityPolicy client-IP authorization on UDPRoute
zhaohuabing Aug 27, 2026
809d17e
test: make the mixed-ordering UDP authorization case cover both direc…
zhaohuabing Aug 27, 2026
1bdbc8c
gatewayapi: fix two L4 SecurityPolicy authorization flaws
zhaohuabing Aug 27, 2026
9aa5371
docs: fix the UDPRoute reference link
zhaohuabing Aug 27, 2026
cc51835
docs: note that IP restriction also applies to TCPRoute and UDPRoute
zhaohuabing Aug 27, 2026
08024ee
test: give the UDP authorization e2e its own coredns backend
zhaohuabing Aug 28, 2026
2147dd1
test: fix yaml sequence indentation in the UDP authorization manifest
zhaohuabing Aug 28, 2026
e98e7b2
test: drop the backend comment from the UDP authorization manifest
zhaohuabing Aug 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 10 additions & 7 deletions api/v1alpha1/authorization_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,17 @@ type Principal struct {
// You can use the `ClientIPDetection` or the `ProxyProtocol` field in
// the `ClientTrafficPolicy` to configure how the client IP is detected.
//
// For TCPRoute targets (raw TCP connections), HTTP headers such as
// For TCPRoute and UDPRoute targets (raw L4 traffic), HTTP headers such as
// X-Forwarded-For are not available. The client IP is obtained from the
// TCP connection's peer address. If intermediaries (load balancers, NAT)
// terminate or proxy TCP, the original client IP will only be available
// if the intermediary preserves the source address (for example by
// enabling the PROXY protocol or avoiding SNAT). Ensure your L4 proxy is
// TCP connection's peer address, or from the source address of the UDP
// datagram. If intermediaries (load balancers, NAT) terminate or proxy the
// traffic, the original client IP will only be available if the
// intermediary preserves the source address (for example by enabling the
// PROXY protocol or avoiding SNAT). Note that the PROXY protocol is not
// available on the UDP path, so a UDPRoute target relies entirely on the
// datagram source address being preserved. Ensure your L4 proxy is
// configured to preserve the source IP to enable correct client-IP
// matching for TCPRoute targets.
// matching for TCPRoute and UDPRoute targets.
// +optional
// +kubebuilder:validation:MinItems=1
ClientCIDRs []CIDR `json:"clientCIDRs,omitempty"`
Expand All @@ -160,7 +163,7 @@ type Principal struct {

// ClientIPGeoLocations authorizes the request based on geolocation metadata derived from the client IP.
// This field is supported for HTTPRoute and GRPCRoute authorization.
// It is not supported for TCPRoute targets.
// It is not supported for TCPRoute or UDPRoute targets.
//
// If multiple entries are specified, one of the ClientIPGeoLocation entries must match for the rule to match.
//
Expand Down
15 changes: 8 additions & 7 deletions api/v1alpha1/securitypolicy_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,19 +37,20 @@ type SecurityPolicy struct {

// SecurityPolicySpec defines the desired state of SecurityPolicy.
//
// NOTE: SecurityPolicy can target Gateway, ListenerSet, HTTPRoute, GRPCRoute, and TCPRoute.
// When a SecurityPolicy targets a TCPRoute, only client-IP CIDR based authorization
// (Authorization rules that use Principal.ClientCIDRs) is applied. Other
// NOTE: SecurityPolicy can target Gateway, ListenerSet, HTTPRoute, GRPCRoute, TCPRoute
// and UDPRoute.
// When a SecurityPolicy targets a TCPRoute or a UDPRoute, only client-IP CIDR based
// authorization (Authorization rules that use Principal.ClientCIDRs) is applied. Other
// authentication/authorization features such as JWT, API Key, Basic Auth,
// OIDC, External Authorization, or GeoIP based authorization are not applicable
// to TCPRoute targets.
// to TCPRoute or UDPRoute targets.
//
// +kubebuilder:validation:XValidation:rule="(has(self.targetRef) && !has(self.targetRefs)) || (!has(self.targetRef) && has(self.targetRefs)) || (has(self.targetSelectors) && self.targetSelectors.size() > 0) ", message="either targetRef or targetRefs must be used"
// +kubebuilder:validation:XValidation:rule="has(self.targetRef) ? self.targetRef.group == 'gateway.networking.k8s.io' : true", message="this policy can only have a targetRef.group of gateway.networking.k8s.io"
// +kubebuilder:validation:XValidation:rule="has(self.targetRef) ? self.targetRef.kind in ['Gateway', 'ListenerSet', 'HTTPRoute', 'GRPCRoute', 'TCPRoute'] : true", message="this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute"
// +kubebuilder:validation:XValidation:rule="has(self.targetRef) ? self.targetRef.kind in ['Gateway', 'ListenerSet', 'HTTPRoute', 'GRPCRoute', 'TCPRoute', 'UDPRoute'] : true", message="this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute"
// +kubebuilder:validation:XValidation:rule="has(self.targetRefs) ? self.targetRefs.all(ref, ref.group == 'gateway.networking.k8s.io') : true ", message="this policy can only have a targetRefs[*].group of gateway.networking.k8s.io"
// +kubebuilder:validation:XValidation:rule="has(self.targetRefs) ? self.targetRefs.all(ref, ref.kind in ['Gateway', 'ListenerSet', 'HTTPRoute', 'GRPCRoute', 'TCPRoute']) : true ", message="this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute"
// +kubebuilder:validation:XValidation:rule="!has(self.mergeType) || ((!has(self.targetRef) || self.targetRef.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute']) && (!has(self.targetRefs) || self.targetRefs.all(ref, ref.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute'])) && (!has(self.targetSelectors) || self.targetSelectors.all(sel, sel.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute'])))", message="mergeType can only be used with xRoute targets"
// +kubebuilder:validation:XValidation:rule="has(self.targetRefs) ? self.targetRefs.all(ref, ref.kind in ['Gateway', 'ListenerSet', 'HTTPRoute', 'GRPCRoute', 'TCPRoute', 'UDPRoute']) : true ", message="this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute"
// +kubebuilder:validation:XValidation:rule="!has(self.mergeType) || ((!has(self.targetRef) || self.targetRef.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute', 'UDPRoute']) && (!has(self.targetRefs) || self.targetRefs.all(ref, ref.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute', 'UDPRoute'])) && (!has(self.targetSelectors) || self.targetSelectors.all(sel, sel.kind in ['HTTPRoute', 'GRPCRoute', 'TCPRoute', 'UDPRoute'])))", message="mergeType can only be used with xRoute targets"
// +kubebuilder:validation:XValidation:rule="(has(self.authorization) && has(self.authorization.rules) && self.authorization.rules.exists(r, has(r.principal) ? has(r.principal.jwt) : false)) ? has(self.jwt) : true", message="if authorization.rules.principal.jwt is used, jwt must be defined"
type SecurityPolicySpec struct {
PolicyTargetReferences `json:",inline"`
Expand Down
35 changes: 20 additions & 15 deletions charts/gateway-crds-helm/templates/generated/gateway.envoyproxy.io_securitypolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -325,14 +325,17 @@ spec:
You can use the `ClientIPDetection` or the `ProxyProtocol` field in
the `ClientTrafficPolicy` to configure how the client IP is detected.

For TCPRoute targets (raw TCP connections), HTTP headers such as
For TCPRoute and UDPRoute targets (raw L4 traffic), HTTP headers such as
X-Forwarded-For are not available. The client IP is obtained from the
TCP connection's peer address. If intermediaries (load balancers, NAT)
terminate or proxy TCP, the original client IP will only be available
if the intermediary preserves the source address (for example by
enabling the PROXY protocol or avoiding SNAT). Ensure your L4 proxy is
TCP connection's peer address, or from the source address of the UDP
datagram. If intermediaries (load balancers, NAT) terminate or proxy the
traffic, the original client IP will only be available if the
intermediary preserves the source address (for example by enabling the
PROXY protocol or avoiding SNAT). Note that the PROXY protocol is not
available on the UDP path, so a UDPRoute target relies entirely on the
datagram source address being preserved. Ensure your L4 proxy is
configured to preserve the source IP to enable correct client-IP
matching for TCPRoute targets.
matching for TCPRoute and UDPRoute targets.
items:
description: |-
CIDR defines a CIDR Address range.
Expand All @@ -345,7 +348,7 @@ spec:
description: |-
ClientIPGeoLocations authorizes the request based on geolocation metadata derived from the client IP.
This field is supported for HTTPRoute and GRPCRoute authorization.
It is not supported for TCPRoute targets.
It is not supported for TCPRoute or UDPRoute targets.

If multiple entries are specified, one of the ClientIPGeoLocation entries must match for the rule to match.

Expand Down Expand Up @@ -8024,21 +8027,23 @@ spec:
- message: this policy can only have a targetRef.group of gateway.networking.k8s.io
rule: 'has(self.targetRef) ? self.targetRef.group == ''gateway.networking.k8s.io''
: true'
- message: this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute
- message: this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute
rule: 'has(self.targetRef) ? self.targetRef.kind in [''Gateway'', ''ListenerSet'',
''HTTPRoute'', ''GRPCRoute'', ''TCPRoute''] : true'
''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute''] : true'
- message: this policy can only have a targetRefs[*].group of gateway.networking.k8s.io
rule: 'has(self.targetRefs) ? self.targetRefs.all(ref, ref.group ==
''gateway.networking.k8s.io'') : true '
- message: this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute
- message: this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute
rule: 'has(self.targetRefs) ? self.targetRefs.all(ref, ref.kind in [''Gateway'',
''ListenerSet'', ''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'']) : true '
''ListenerSet'', ''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute''])
: true '
- message: mergeType can only be used with xRoute targets
rule: '!has(self.mergeType) || ((!has(self.targetRef) || self.targetRef.kind
in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'']) && (!has(self.targetRefs)
|| self.targetRefs.all(ref, ref.kind in [''HTTPRoute'', ''GRPCRoute'',
''TCPRoute''])) && (!has(self.targetSelectors) || self.targetSelectors.all(sel,
sel.kind in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute''])))'
in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute'']) &&
(!has(self.targetRefs) || self.targetRefs.all(ref, ref.kind in [''HTTPRoute'',
''GRPCRoute'', ''TCPRoute'', ''UDPRoute''])) && (!has(self.targetSelectors)
|| self.targetSelectors.all(sel, sel.kind in [''HTTPRoute'', ''GRPCRoute'',
''TCPRoute'', ''UDPRoute''])))'
- message: if authorization.rules.principal.jwt is used, jwt must be defined
rule: '(has(self.authorization) && has(self.authorization.rules) &&
self.authorization.rules.exists(r, has(r.principal) ? has(r.principal.jwt)
Expand Down
35 changes: 20 additions & 15 deletions charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,14 +324,17 @@ spec:
You can use the `ClientIPDetection` or the `ProxyProtocol` field in
the `ClientTrafficPolicy` to configure how the client IP is detected.

For TCPRoute targets (raw TCP connections), HTTP headers such as
For TCPRoute and UDPRoute targets (raw L4 traffic), HTTP headers such as
X-Forwarded-For are not available. The client IP is obtained from the
TCP connection's peer address. If intermediaries (load balancers, NAT)
terminate or proxy TCP, the original client IP will only be available
if the intermediary preserves the source address (for example by
enabling the PROXY protocol or avoiding SNAT). Ensure your L4 proxy is
TCP connection's peer address, or from the source address of the UDP
datagram. If intermediaries (load balancers, NAT) terminate or proxy the
traffic, the original client IP will only be available if the
intermediary preserves the source address (for example by enabling the
PROXY protocol or avoiding SNAT). Note that the PROXY protocol is not
available on the UDP path, so a UDPRoute target relies entirely on the
datagram source address being preserved. Ensure your L4 proxy is
configured to preserve the source IP to enable correct client-IP
matching for TCPRoute targets.
matching for TCPRoute and UDPRoute targets.
items:
description: |-
CIDR defines a CIDR Address range.
Expand All @@ -344,7 +347,7 @@ spec:
description: |-
ClientIPGeoLocations authorizes the request based on geolocation metadata derived from the client IP.
This field is supported for HTTPRoute and GRPCRoute authorization.
It is not supported for TCPRoute targets.
It is not supported for TCPRoute or UDPRoute targets.

If multiple entries are specified, one of the ClientIPGeoLocation entries must match for the rule to match.

Expand Down Expand Up @@ -8023,21 +8026,23 @@ spec:
- message: this policy can only have a targetRef.group of gateway.networking.k8s.io
rule: 'has(self.targetRef) ? self.targetRef.group == ''gateway.networking.k8s.io''
: true'
- message: this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute
- message: this policy can only have a targetRef.kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute
rule: 'has(self.targetRef) ? self.targetRef.kind in [''Gateway'', ''ListenerSet'',
''HTTPRoute'', ''GRPCRoute'', ''TCPRoute''] : true'
''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute''] : true'
- message: this policy can only have a targetRefs[*].group of gateway.networking.k8s.io
rule: 'has(self.targetRefs) ? self.targetRefs.all(ref, ref.group ==
''gateway.networking.k8s.io'') : true '
- message: this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute
- message: this policy can only have a targetRefs[*].kind of Gateway/ListenerSet/HTTPRoute/GRPCRoute/TCPRoute/UDPRoute
rule: 'has(self.targetRefs) ? self.targetRefs.all(ref, ref.kind in [''Gateway'',
''ListenerSet'', ''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'']) : true '
''ListenerSet'', ''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute''])
: true '
- message: mergeType can only be used with xRoute targets
rule: '!has(self.mergeType) || ((!has(self.targetRef) || self.targetRef.kind
in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'']) && (!has(self.targetRefs)
|| self.targetRefs.all(ref, ref.kind in [''HTTPRoute'', ''GRPCRoute'',
''TCPRoute''])) && (!has(self.targetSelectors) || self.targetSelectors.all(sel,
sel.kind in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute''])))'
in [''HTTPRoute'', ''GRPCRoute'', ''TCPRoute'', ''UDPRoute'']) &&
(!has(self.targetRefs) || self.targetRefs.all(ref, ref.kind in [''HTTPRoute'',
''GRPCRoute'', ''TCPRoute'', ''UDPRoute''])) && (!has(self.targetSelectors)
|| self.targetSelectors.all(sel, sel.kind in [''HTTPRoute'', ''GRPCRoute'',
''TCPRoute'', ''UDPRoute''])))'
- message: if authorization.rules.principal.jwt is used, jwt must be defined
rule: '(has(self.authorization) && has(self.authorization.rules) &&
self.authorization.rules.exists(r, has(r.principal) ? has(r.principal.jwt)
Expand Down
Loading