feat: initial proxy protocol support #12979

yuval-k · 2025-11-25T15:28:51Z

Description

Add proxy protocol support to listeners

Change Type

/kind feature

Changelog

Add a ListenerPolicy CRD and ProxyProtocol config in it.

Addition Notes:
In the future we might make HTTPListenerPolicy and http field in this policy

Signed-off-by: Yuval Kohavi <[email protected]>

puertomontt · 2025-11-25T22:36:22Z

api/v1alpha1/listener_policy_types.go

+// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=Direct"
+// ListenerPolicy is used for configuring Envoy listener-level settings that apply to all protocol types (HTTP, HTTPS, TCP, TLS).
+// This includes listener filters such as PROXY protocol support.
+// These policies can be applied per Gateway (and in the future maybe per listener port, to target specific ports).


Suggested change

// These policies can be applied per Gateway (and in the future maybe per listener port, to target specific ports).

// These policies can be applied per Gateway.

remove or add a TODO?

Signed-off-by: Yuval Kohavi <[email protected]>

Copilot

Pull request overview

This PR introduces initial PROXY protocol support for kgateway by adding a new ListenerPolicy CRD. The implementation allows users to enable PROXY protocol on Gateway listeners, which is commonly used when kgateway sits behind a load balancer that needs to preserve client IP information.

Key Changes:

Introduces a new ListenerPolicy CRD with ProxyProtocol configuration
Implements listener-level plugin that adds Envoy PROXY protocol filter
Adds comprehensive test coverage including unit tests, translator tests, and e2e tests

Reviewed changes

Copilot reviewed 34 out of 36 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`api/v1alpha1/listener_policy_types.go`	Defines the new ListenerPolicy CRD and ProxyProtocolConfig types
`internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go`	Implements the listener policy plugin that applies PROXY protocol configuration to Envoy listeners
`internal/kgateway/extensions2/registry/registry.go`	Registers the new listener policy plugin
`internal/kgateway/wellknown/kgw.go`	Adds GVK/GVR definitions for ListenerPolicy
`pkg/client/clientset/versioned/typed/api/v1alpha1/listenerpolicy.go`	Generated client code for ListenerPolicy CRD
`install/helm/kgateway-crds/templates/gateway.kgateway.dev_listenerpolicies.yaml`	CRD definition for ListenerPolicy
`install/helm/kgateway/templates/role.yaml`	Adds RBAC permissions for listenerpolicies resource
`test/e2e/features/listener_policy_proxy_protocol/suite.go`	E2E test suite validating proxy protocol behavior
`test/e2e/features/listener_policy_proxy_protocol/testdata/setup.yaml`	Test manifests for nginx backend and curl client
`internal/kgateway/translator/gateway/gateway_translator_test.go`	Unit tests for HTTP, HTTPS, and TCP proxy protocol scenarios
`pkg/utils/requestutils/curl/request.go`	Adds support for PROXY protocol header in curl utility

Comments suppressed due to low confidence (1)

internal/kgateway/translator/gateway/gateway_translator_test.go:2061

This test function appears to be debug/development code that should be removed before merging. The function name "TestSomethin" is incomplete and the test doesn't have a clear purpose in the context of this PR. Additionally, line 2048 has a bug where BBcli is typed as HTTPListenerPolicy but uses wellknown.ListenerPolicyGVR instead of wellknown.HTTPListenerPolicyGVR.

		settingOpts := []translatortest.SettingsOpts{
			func(s *apisettings.Settings) {
				s.DiscoveryNamespaceSelectors = cfgJSON
				s.EnableExperimentalGatewayAPIFeatures = true
			},
		}

		translatortest.TestTranslation(t, ctx, inputFiles, expectedOutputFile, gwNN, settingOpts...)
	}
	t.Run("Select all resources", func(t *testing.T) {
		test(t, `[
  {
    "matchExpressions": [
      {
        "key": "kubernetes.io/metadata.name",
        "operator": "In",
        "values": [
          "infra"
        ]
      }
    ]
  },
	{
		"matchLabels": {
			"app": "a"
		}
	}
]`, "base.yaml", "base_select_all.yaml")
	})

	t.Run("Select all resources; AND matchExpressions and matchLabels", func(t *testing.T) {
		test(t, `[
  {
    "matchExpressions": [
      {
        "key": "kubernetes.io/metadata.name",
        "operator": "In",
        "values": [
          "infra"
        ]
      }
    ]
  },
	{
    "matchExpressions": [

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go

Signed-off-by: Yuval Kohavi <[email protected]>

lgadban

I am onboard with the new ListenerPolicy CRD for this and the code mostly LGTM.

Just a few minor comments on API docs etc

lgadban · 2025-11-26T16:17:09Z

api/v1alpha1/listener_policy_types.go

+// ListenerPolicySpec defines the desired state of a listener policy.
+type ListenerPolicySpec struct {
+	// TargetRefs specifies the target resources by reference to attach the policy to.
+	// Supports Gateway and XListenerSet resources. Use sectionName to target specific listeners by port.


This comment is incorrect right? Only Gateway attachment and no sectionName support

right - the comment is not right - i think i fixed the CEL validation but missed that one

lgadban · 2025-11-26T16:52:07Z

api/v1alpha1/listener_policy_types.go

+// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=Direct"
+// ListenerPolicy is used for configuring Envoy listener-level settings that apply to all protocol types (HTTP, HTTPS, TCP, TLS).
+// This includes features such as PROXY protocol support.
+// These policies can targetRef Gateway objects.


Suggested change

// These policies can targetRef Gateway objects.

// These policies can only target `Gateway` objects.

lgadban · 2025-11-26T16:52:35Z

api/v1alpha1/listener_policy_types.go

+// +kubebuilder:subresource:status
+// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=Direct"
+// ListenerPolicy is used for configuring Envoy listener-level settings that apply to all protocol types (HTTP, HTTPS, TCP, TLS).
+// This includes features such as PROXY protocol support.


do you think it's worth including this in the comments?
we'll need to constantly be updating it etc?

i can remove

lgadban · 2025-11-26T16:57:49Z

internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go

+	return d.ct
+}
+
+func (d *listenerPolicy) Equals(in any) bool {


any reason to not compare ct in here?

I am also surprised the krtEquals linter is not complaining that it is omitted
cc @timflannagan

it's not needed in equals because it doesn't impact policy. it's used to determine ordering if there are multiple policies

hmm actually that merging thing can impact policy. ok i'll add

I am also surprised the krtEquals linter is not complaining that it is omitted

I think creating an issue to investigate further is worthwhile imo.

lgadban · 2025-11-26T16:59:27Z

internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go

+	logger.Debug("applying to listener", "listener", out.Name, "policyType", fmt.Sprintf("%T", pCtx.Policy))
+	pol, ok := pCtx.Policy.(*listenerPolicy)
+	if !ok || pol == nil {
+		logger.Debug("policy is not listenerPolicy type or is nil", "ok", ok, "pol", pol)


is this a realistic concern? if so, maybe this should a warn instead

lgadban · 2025-11-26T17:03:57Z

api/v1alpha1/listener_policy_types.go

+	// +kubebuilder:validation:XValidation:rule="self.all(r, r.kind == 'Gateway' && (!has(r.group) || r.group == 'gateway.networking.k8s.io'))",message="targetRefs may only reference Gateway resource"
+	TargetRefs []LocalPolicyTargetReference `json:"targetRefs,omitempty"`
+
+	// TargetSelectors specifies the target selectors to select resources to attach the policy to.


Suggested change

// TargetSelectors specifies the target selectors to select resources to attach the policy to.

// TargetSelectors specifies the target selectors to select `Gateway` resources to attach the policy to.

internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go

lgadban · 2025-11-26T17:08:38Z

internal/kgateway/translator/gateway/gateway_translator_test.go

 	})
 }
+
+func TestSomethin(t *testing.T) {


what is this thing? 😆

ah whops! i added that to debug something and forgot to remove; i'll delete

lgadban · 2025-11-26T17:09:15Z

...al/kgateway/translator/gateway/testutils/outputs/gateway-only/tls-multiple-certificates.yaml

was this just local formatting changes?

i'll check maybe i refreshed goldens on other tests by mistake

lgadban · 2025-11-26T17:09:21Z

...nal/kgateway/translator/gateway/testutils/outputs/tcp-routing/tls-multiple-certificates.yaml

was this just local formatting changes?

Signed-off-by: Yuval Kohavi <[email protected]>

timflannagan · 2025-11-26T22:00:08Z

go.mod

 	go.uber.org/zap v1.27.0
 	golang.org/x/exp v0.0.0-20251017212417-90e834f514db
-	golang.org/x/net v0.46.0
+	golang.org/x/net v0.46.0 // indirect


We should move this outside of the direct dependency require block imo.

timflannagan · 2025-11-26T22:02:29Z

internal/kgateway/extensions2/plugins/listenerpolicy/listener_plugin.go

+	// Marshal to Any
+	proxyProtocolAny, err := utils.MessageToAny(proxyProtocolConfig)
+	if err != nil {
+		logger.Error("failed to marshal proxy protocol config",
+			"error", err)
+	}


We could also return this error and propagate to the IR's Error field. AFAIK, we don't handle errors on the IR for the HLP IR though.

it should never happen, i thought to panic here but ended up doing the log. maybe i should add a panic

timflannagan · 2025-11-26T22:03:45Z

internal/kgateway/translator/irtranslator/gateway.go

 	envoyclusterv3 "github.com/envoyproxy/go-control-plane/envoy/config/cluster/v3"
 	envoylistenerv3 "github.com/envoyproxy/go-control-plane/envoy/config/listener/v3"
 	envoyroutev3 "github.com/envoyproxy/go-control-plane/envoy/config/route/v3"
-	"golang.org/x/net/context"


😆 nice catch.

timflannagan · 2025-11-26T22:04:47Z

test/e2e/features/listener_policy_proxy_protocol/suite.go

+func NewTestingSuite(ctx context.Context, testInst *e2e.TestInstallation) suite.TestingSuite {
+	return &testingSuite{
+		ctx:              ctx,
+		testInstallation: testInst,
+	}
+}


We've been trying to use base.BaseTestingSuite as much as possible (or at least there's been a lot of movement on standardizing on that). Something to teach AGENTS.md at some point too.

timflannagan · 2025-11-26T22:05:23Z

test/e2e/features/listener_policy_proxy_protocol/testdata/setup.yaml

I think curl and nginx are both available as testdefault manifests. We could use those instead of defining net new manifests as much as possible.

Signed-off-by: Yuval Kohavi <[email protected]>

initial proxy protocol support

883cb9b

Signed-off-by: Yuval Kohavi <[email protected]>

gateway-bot added kind/feature Categorizes issue or PR as related to a new feature. release-note labels Nov 25, 2025

puertomontt reviewed Nov 25, 2025

View reviewed changes

yuval-k added 4 commits November 25, 2025 22:16

add e2e test

56bedfa

Signed-off-by: Yuval Kohavi <[email protected]>

fix comment

e0a8750

Signed-off-by: Yuval Kohavi <[email protected]>

Merge remote-tracking branch 'origin/main' into yuval-k/proxy-proto

89094b4

Signed-off-by: Yuval Kohavi <[email protected]>

add status markers

bc49a08

Signed-off-by: Yuval Kohavi <[email protected]>

yuval-k marked this pull request as ready for review November 26, 2025 11:26

Copilot AI review requested due to automatic review settings November 26, 2025 11:26

Copilot started reviewing on behalf of yuval-k November 26, 2025 11:26 View session

Copilot finished reviewing on behalf of yuval-k November 26, 2025 11:28

Copilot AI reviewed Nov 26, 2025

View reviewed changes

yuval-k added 2 commits November 26, 2025 08:31

lint and verify

2016187

Signed-off-by: Yuval Kohavi <[email protected]>

log to debug

89b8467

Signed-off-by: Yuval Kohavi <[email protected]>

yuval-k enabled auto-merge November 26, 2025 16:21

lgadban reviewed Nov 26, 2025

View reviewed changes

yuval-k added 7 commits November 26, 2025 15:19

PR comments

4d87b0c

Signed-off-by: Yuval Kohavi <[email protected]>

add e2e test to CI

4bcab2d

Signed-off-by: Yuval Kohavi <[email protected]>

lint

7f3b73e

Signed-off-by: Yuval Kohavi <[email protected]>

Merge remote-tracking branch 'origin/main' into yuval-k/proxy-proto

32f0d89

Signed-off-by: Yuval Kohavi <[email protected]>

fix merge; make analyze

5db7afc

Signed-off-by: Yuval Kohavi <[email protected]>

tidy

81f62b7

Signed-off-by: Yuval Kohavi <[email protected]>

gen

d6d545c

Signed-off-by: Yuval Kohavi <[email protected]>

timflannagan approved these changes Nov 26, 2025

View reviewed changes

yuval-k added this pull request to the merge queue Nov 26, 2025

Merged via the queue into main with commit c81a45b Nov 26, 2025
30 checks passed

yuval-k deleted the yuval-k/proxy-proto branch November 26, 2025 22:30

lgadban mentioned this pull request Nov 27, 2025

Add support for Downstream Proxy Protocol #11161

Closed

lgadban mentioned this pull request Dec 1, 2025

ListenerPolicy follow up #13012

Open

4 tasks

yuval-k added a commit that referenced this pull request Dec 1, 2025

feat: initial proxy protocol support (#12979)

aacc002

Signed-off-by: Yuval Kohavi <[email protected]>

lgadban mentioned this pull request Dec 31, 2025

Add EP for Proxy protocol support #13211

Open

	// These policies can be applied per Gateway (and in the future maybe per listener port, to target specific ports).
	// These policies can be applied per Gateway.

	// These policies can targetRef Gateway objects.
	// These policies can only target `Gateway` objects.

	// TargetSelectors specifies the target selectors to select resources to attach the policy to.
	// TargetSelectors specifies the target selectors to select `Gateway` resources to attach the policy to.

feat: initial proxy protocol support #12979

feat: initial proxy protocol support #12979

Uh oh!

Conversation

yuval-k commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Change Type

Changelog

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes:

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lgadban left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

yuval-k commented Nov 25, 2025 •

edited

Loading