Skip to content

docs: Add documentation for ListenerSets - #4568

Merged
k8s-ci-robot merged 13 commits into
kubernetes-sigs:mainfrom
davidjumani:ls-docs
Feb 27, 2026
Merged

k8s-ci-robot merged 13 commits into
kubernetes-sigs:mainfrom
davidjumani:ls-docs

Conversation

@davidjumani

@davidjumani davidjumani commented Feb 19, 2026 •

Copy link
Copy Markdown
Contributor

What type of PR is this?

/kind documentation

What this PR does / why we need it:
This PR adds docs on ListenerSets which was promoted in v1.5

https://deploy-preview-4568--kubernetes-sigs-gateway-api.netlify.app/api-types/listenerset/
https://deploy-preview-4568--kubernetes-sigs-gateway-api.netlify.app/guides/listener-set/

Which issue(s) this PR fixes:
Ref #4249

Does this PR introduce a user-facing change?:

Adds documentation around ListenerSets

@k8s-ci-robot k8s-ci-robot added do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 19, 2026
@k8s-ci-robot k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 19, 2026
@davidjumani davidjumani changed the title Add docs for listenerSets docs: Add documentation for ListenerSets Feb 19, 2026
@k8s-ci-robot k8s-ci-robot added release-note Denotes a PR that will be considered when it comes time to generate release notes. and removed do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Feb 19, 2026
@davidjumani

Copy link
Copy Markdown
Contributor Author

/retest

1 similar comment
@davidjumani

Copy link
Copy Markdown
Contributor Author

/retest

Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/guides/listener-set.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
- [TCP routing](../tcp.md)
- [gRPC routing](../grpc-routing.md)

- [ListenerSets] (../listener-set.md)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
- [ListenerSets] (../listener-set.md)
- [ListenerSets](../listener-set.md)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

+1, would go one step further and recommend that both name and path share the same pluralization, so listener-sets.md

Comment thread site-src/guides/listener-set.md Resolved
spec:
parentRef:
name: parent-gateway
kind: Gateway

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Do we need namespace here?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Only if it is in a different namespace

Comment thread site-src/guides/listener-set.md Resolved

@robscott robscott left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks @davidjumani!

A ListenerSet uses a parentRef to point to a specific Gateway

```yaml
apiVersion: gateway.networking.k8s.io/v1

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

For any examples that are a valid and complete resource, please use separate files in /examples and then embed them here - look at other guides for an example. Doing that allows our automated checks to ensure all the examples in our docs are valid.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks, updated

Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
- [TCP routing](../tcp.md)
- [gRPC routing](../grpc-routing.md)

- [ListenerSets] (../listener-set.md)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

+1, would go one step further and recommend that both name and path share the same pluralization, so listener-sets.md

Comment thread site-src/guides/listener-set.md Resolved
Comment thread site-src/guides/listener-set.md Resolved
Comment thread site-src/guides/listener-set.md Outdated
certificateRefs:
- kind: Secret
group: ""
name: first-workload-cert # Provisioned via HTTP01 challenge

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This comment doesn't really seem to make sense unless we're also showing users how to use a system that would provision a cert for them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Removed the comment

is automatically marked with a `Conflicted: True` status and remains inactive until the higher-priority
resource is removed, ensuring a secure and predictable traffic flow.

## Examples

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think the most critical example would likely be to show how to delegate TLS configuration to different namespaces. Likely with the following steps:

  1. Create Gateway that allows ListenerSets to attach from namespaces labeled shared-gateway
  2. Label 1 namespace shared-gateway
  3. Create a ListenerSet in that namespace and reference a TLS cert

This is not a blocker for this PR, just a suggestion for what might be more compelling, particularly for users coming from ingress-nginx.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Updated the example and moved it to examples/standard

davidjumani and others added 3 commits February 23, 2026 14:14
Co-authored-by: Suvin Nimnaka <hello@suvin.me>
Co-authored-by: Rob Scott <rob.scott87@gmail.com>
@davidjumani

Copy link
Copy Markdown
Contributor Author

Thanks @Suvink @robscott for taking the time to review this. I've addressed the comments

@davidjumani

Copy link
Copy Markdown
Contributor Author

/retest

Comment thread site-src/guides/listener-set.md Resolved
Comment thread site-src/guides/listener-set.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
Comment thread site-src/api-types/listenerset.md Resolved
@k8s-ci-robot k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 24, 2026
@k8s-ci-robot k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Feb 24, 2026
@davidjumani

Copy link
Copy Markdown
Contributor Author

Thanks @youngnick I've applied the suggestions

@youngnick

Copy link
Copy Markdown
Contributor

I think this looks pretty good now, so I'll approve and hold for other folks.

/approve
/hold

@k8s-ci-robot k8s-ci-robot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Feb 24, 2026
@davidjumani

Copy link
Copy Markdown
Contributor Author

/retest

@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: davidjumani, Suvink, youngnick

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

The pull request process is described here

Details Needs approval from an approver in each of these files:

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

@kflynn

kflynn commented Feb 27, 2026

Copy link
Copy Markdown
Contributor

/hold cancel

now that 1.5 is out. 🙂 Thanks, @davidjumani!

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Feb 27, 2026
@kflynn

kflynn commented Feb 27, 2026

Copy link
Copy Markdown
Contributor

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 27, 2026
@k8s-ci-robot
k8s-ci-robot merged commit 7be5498 into kubernetes-sigs:main Feb 27, 2026
20 checks passed
@davidjumani davidjumani mentioned this pull request Mar 2, 2026
1 task done
danehans pushed a commit to danehans/gateway-api that referenced this pull request Mar 10, 2026
* Add docs for listenerSets

* add guide to index

* fix markdown

* add api type

* update navigation

* Apply suggestions from code review

Co-authored-by: Suvin Nimnaka <hello@suvin.me>
Co-authored-by: Rob Scott <rob.scott87@gmail.com>

* address some more comments

* update example

* update doc

* Apply suggestions from code review

Co-authored-by: Nick Young <inocuo@gmail.com>

---------

Co-authored-by: Suvin Nimnaka <hello@suvin.me>
Co-authored-by: Rob Scott <rob.scott87@gmail.com>
Co-authored-by: Nick Young <inocuo@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note Denotes a PR that will be considered when it comes time to generate release notes. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants