Improve some ListenetSet gep descriptions #3978

rikatz · 2025-08-07T17:29:25Z

What type of PR is this?
/kind gep

What this PR does / why we need it:
This PR is a review of ListenerSet GEP, fixing some manifests and adding some comments to be further discussed

Which issue(s) this PR fixes:

Fixes #

Does this PR introduce a user-facing change?:

NONE

k8s-ci-robot · 2025-08-07T17:29:32Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: rikatz
Once this PR has been reviewed and has the lgtm label, please assign thockin for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

geps/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

rikatz · 2025-08-07T17:29:43Z

geps/gep-1713/index.md

@@ -59,7 +59,7 @@ type GatewaySpec struct {
 }

 type AllowedListeners struct {
-	// +kubebuilder:default={from:Same}
+	// +kubebuilder:default={from: None}


this was made to reflect the current implementation

I may be out of context, wdym here? are we moving away from the Same as default?

on the API definition Same is not the default, None is:

gateway-api/apis/v1/gateway_types.go

Line 306 in fb75360

// +kubebuilder:default={from: None}

LiorLieberman

Thanks!

LiorLieberman · 2025-08-07T17:34:24Z

geps/gep-1713/index.md

@@ -59,7 +59,7 @@ type GatewaySpec struct {
 }

 type AllowedListeners struct {
-	// +kubebuilder:default={from:Same}
+	// +kubebuilder:default={from: None}


I may be out of context, wdym here? are we moving away from the Same as default?

LiorLieberman · 2025-08-07T17:36:39Z

geps/gep-1713/index.md

-
+To attach to listeners in both a `Gateway` and `ListenerSet` the route MUST have two `parentRefs`:
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
  name: httproute-example
 spec:
  parentRefs:
-  - name: some-workload-listeners
+  - name: second-workload-listeners
    kind: ListenerSet
+    sectionName: second
+  - name: parent-gateway
+    kind: Gateway
    sectionName: foo
 ```

-To attach to listeners in both a `Gateway` and `ListenerSet` the route MUST have two `parentRefs`:
+For instance, the following `HTTPRoute` attempts to attach to a listener defined in the parent `Gateway` using the sectionName `foo`. This is not valid and the route's status `Accepted` condition should be set to `False`
+
 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
  name: httproute-example
 spec:
  parentRefs:
-  - name: second-workload-listeners
-    kind: ListenerSet
-    sectionName: second
-  - name: parent-gateway
+  - name: some-workload-listeners


I guess no real change here, just order, right?

right, I wrote on my self review why I did the change. The example of the attachment of Gateway AND ListenerSet is more clear on this order, then we can go to the invalid examples :)

To make this invalid the kind needs to be a ListenerSet in the parentRef

LiorLieberman · 2025-08-07T17:37:04Z

geps/gep-1713/index.md

    kind: Gateway
    sectionName: foo
 ```
+>--- Ricardo - above is a bit confusing, maybe ask Dave some clarification


/cc @dprotaso

geps/gep-1713/index.md

rikatz · 2025-08-07T18:05:36Z

geps/gep-1713/index.md

 ```yaml
 apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
  name: parent-gateway
 spec:
  gatewayClassName: example
+  allowedListeners:


per the api spec, not having an allowedListener means "None" which would make this invalid, so I am fixing the example for at least same namespace

rikatz · 2025-08-07T18:10:38Z

geps/gep-1713/index.md

@@ -417,7 +424,8 @@ metadata:
  name: parent-gateway
 spec:
  allowedListeners:
-  - from: Same
+    namespaces:


allowedListeners is not an array, so changing here to reflect the current implemented API

rikatz · 2025-08-07T18:11:33Z

geps/gep-1713/index.md

@@ -438,35 +446,38 @@ spec:
    sectionName: second
 ```

-For instance, the following `HTTPRoute` attempts to attach to a listener defined in the parent `Gateway` using the sectionName `foo`. This is not valid and the route's status `Accepted` condition should be set to `False`
-
+To attach to listeners in both a `Gateway` and `ListenerSet` the route MUST have two `parentRefs`:


I have changed the order of examples here to make it clear what means using two parentRefs, before the next example which is an invalid example

Reading this now it is a duplicate of Routes MUST be able to attach to a ListenerSetand it's parentGatewayby having multipleparentRefs eg:

I saw we replace the above yaml

apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: httproute-example spec: parentRefs: - name: second-workload-listeners kind: ListenerSet sectionName: second

with the yaml containing two parent refs

rikatz · 2025-08-07T18:13:45Z

geps/gep-1713/index.md

    kind: Gateway
    sectionName: foo
 ```
+>--- Ricardo - above is a bit confusing, maybe ask Dave some clarification


@dprotaso the example above is a bit confusing for me, probably because the API changed from when it was implemented.

I was wondering what it means for an HTTPRoute to try to attach a listener defined on a Gateway, using a section name foo. If this section name exists on the Gateway it is valid, right? eg.:

listeners: - name: foo port: 80 protocol: HTTP

So how can the situation above be invalid? Maybe we can get the full yaml definition, with Gateway, ListenerSet and HTTPRoute for clarification here?

Thanks!

See: https://github.com/kubernetes-sigs/gateway-api/pull/3978/files#r2267789208

rikatz · 2025-08-07T18:18:47Z

One extra question I have on ListenerSet that is not clear for me, is the deduplication of listeners from different namespaces.

Let me add an example:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: parent-gateway
  namespace: infra
spec:
  allowedListeners:
    namespaces:
      from: All
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: ListenerSet
metadata:
  name: listener01
  namespace: user01
spec:
  parentRef:
    name: parent-gateway
    namespace: infra
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - name: something
    hostname: something.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: cert
---
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: ListenerSet
metadata:
  name: listener01
  namespace: user02
spec:
  parentRef:
    name: parent-gateway
    namespace: infra
    kind: Gateway
    group: gateway.networking.k8s.io
  listeners:
  - name: something
    hostname: something.foo.com
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        group: ""
        name: othercert

Who owns something.foo.com here? because in this case, if we are not explicitly deduplicating, we may have a situation where 2 listeners for the same host and different cert are set.

rikatz · 2025-08-07T23:48:48Z

on ListenerSet conflict management: at some point on this GEP there is a mention to it:

Listeners in a Gateway and their attached ListenerSets are concatenated as a list when programming the underlying infrastructure

Listeners should be merged using the following precedence:

    "parent" Gateway
    ListenerSet ordered by creation time (oldest first)
    ListenerSet ordered alphabetically by "{namespace}/{name}".

This is the statement for conflict management, but it is not really clear on what a conflict means. This way, during a discussion on gateway-api channel, we've reached the consensus of writing some conflict examples and how to deal with them, as part of the GEP, to make it easier on implementation and conformance.

youngnick · 2025-08-08T00:00:20Z

Thanks @rikatz.

To bring the comments I had in the Slack thread here:

I think there should be two rules:

ListenerSets cannot be Accepted unless all Listeners are distinct (see the Gateway Spec listeners field for an exact definition).
If Listeners within a group of ListenerSets are not distinct (that is, if Listeners in different ListenerSet objects that attach to the same Gateway are not distinct), then the Listeners are conflicting, and the Listener from the oldest ListenerSet object wins and is Accepted. ListenerSets containing conflicting Listeners MUST set the Conflicted Condition to true and clearly indicate which Listeners are conflicted.

Examples that illustrate those rules would be awesome.

rikatz · 2025-08-11T17:57:51Z

@youngnick added some examples and a whole section for conflict management, let me know wdyt :)

dprotaso · 2025-08-11T18:30:07Z

geps/gep-1713/index.md

@@ -115,6 +115,16 @@ type ListenerSetSpec struct {
 	// 2. ListenerSet ordered by creation time (oldest first)
 	// 3. ListenerSet ordered alphabetically by “{namespace}/{name}”.
 	//
+	// Regarding Conflict Management, Listeners in a ListenerSet follow the same


Should we add this new clause to the API types godoc?

Also we might want to call out sectionName behaves a bit differently where sibling ListenerSets can have the same sectionName.

dprotaso · 2025-08-11T18:54:30Z

geps/gep-1713/index.md

+    hostname: www.something.tld
+    protocol: HTTPS
+    port: 443
+	tls:


tab instead of space maybe?

dprotaso · 2025-08-11T19:06:19Z

geps/gep-1713/index.md

 The following example shows a `Gateway` with an HTTP listener and two child HTTPS `ListenerSets` with unique hostnames and certificates.

+Only `ListenerSets` from the same namespace of the `Gateway` will be accepted:


Suggested change

The following example shows a `Gateway` with an HTTP listener and two child HTTPS `ListenerSets` with unique hostnames and certificates.

Only `ListenerSets` from the same namespace of the `Gateway` will be accepted:

The following example shows a `Gateway` with an HTTP listener and two child HTTPS `ListenerSets` with unique hostnames and certificates. Only `ListenerSets` from the same namespace of the `Gateway` will be accepted:

dprotaso · 2025-08-11T19:25:07Z

geps/gep-1713/index.md

-Conflicts are covered in the section 'ListenerConditions within a ListenerSet'
+Conflicts are covered in the section [Listener and ListenerSet conflicts](#listener-and-listenerset-conflicts)
+
+### Listener and ListenerSet conflicts


We should combine this section into ListenerConditions within a ListenerSet so that conflicts are covered in one section.

dprotaso · 2025-08-11T19:25:51Z

geps/gep-1713/index.md

+management.
+
+With ListenerSet this validation should happen within the same ListenerSet resource, 
+but MUST be validated also within a Gateway scope and all of the attached Listeners/ListenerSets.


this language needs to exclude sectionName when comparing it across sibling Listeners

Or refer to 'Optional Section Name'

dprotaso · 2025-08-11T19:42:31Z

geps/gep-1713/index.md

+    hostname: www.something.tld
+    protocol: HTTPS
+    port: 443
+	conditions:


using a tab here instead of spaces

There's a bunch of these places - just view the GitHub rendering of the GEP and you'll see broken syntax formatting

dprotaso · 2025-08-11T19:44:43Z

geps/gep-1713/index.md

+```
+
+The ListenerSet `user-listenerset` should be marked as Conflicted, as the `parent-gateway`
+have a listener definition called `foo` that conflicts with the ListenetSet definition


Suggested change

have a listener definition called `foo` that conflicts with the ListenetSet definition

The ListenerSet `user-listenerset` should be marked as Conflicted, as the `parent-gateway`

has a listener definition called `foo` that conflicts with the ListenerSet definition

called `myapp`, as the following:

Can we also update this (the paragraph not the condition message) to highlight that it is a conflict because the host name is the same but they use different termination TLS certificates

dprotaso · 2025-08-11T19:58:55Z

geps/gep-1713/index.md

+    protocol: HTTPS
+    port: 443
+	conditions:
+    - message: ListenerSet has conflicts with Gateway 'infra/parent-gateway'


Would we want to highlight the listener name in the error message?

Improve some ListenetSet gep descriptions

7239e0d

k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/gep PRs related to Gateway Enhancement Proposal(GEP) cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Aug 7, 2025

k8s-ci-robot requested a review from candita August 7, 2025 17:29

k8s-ci-robot requested a review from LiorLieberman August 7, 2025 17:29

k8s-ci-robot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 7, 2025

rikatz commented Aug 7, 2025

View reviewed changes

LiorLieberman reviewed Aug 7, 2025

View reviewed changes

k8s-ci-robot requested a review from dprotaso August 7, 2025 17:37

rikatz commented Aug 7, 2025

View reviewed changes

geps/gep-1713/index.md Outdated Show resolved Hide resolved

rikatz commented Aug 7, 2025

View reviewed changes

Add examples of conflicting ListenerSets

48fdd71

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 11, 2025

dprotaso reviewed Aug 11, 2025

View reviewed changes

geps/gep-1713/index.md

hostname: www.something.tld

protocol: HTTPS

port: 443

tls:

Copy link

Contributor

dprotaso Aug 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tab instead of space maybe?

dprotaso reviewed Aug 11, 2025

View reviewed changes

		The following example shows a `Gateway` with an HTTP listener and two child HTTPS `ListenerSets` with unique hostnames and certificates.

		Only `ListenerSets` from the same namespace of the `Gateway` will be accepted:

Improve some ListenetSet gep descriptions #3978

Are you sure you want to change the base?

Improve some ListenetSet gep descriptions #3978

Conversation

rikatz commented Aug 7, 2025

Uh oh!

k8s-ci-robot commented Aug 7, 2025

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!

LiorLieberman 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!

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!

rikatz commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rikatz commented Aug 7, 2025

Uh oh!

youngnick commented Aug 8, 2025

Uh oh!

rikatz commented Aug 11, 2025

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!

dprotaso Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dprotaso Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rikatz commented Aug 7, 2025 •

edited

Loading

dprotaso Aug 11, 2025 •

edited

Loading

dprotaso Aug 11, 2025 •

edited

Loading