Skip to content

EXP: UDPRoute - #4720

Merged
k8s-ci-robot merged 2 commits into
kubernetes-sigs:mainfrom
zac-nixon:main
May 2, 2026
Merged

k8s-ci-robot merged 2 commits into
kubernetes-sigs:mainfrom
zac-nixon:main

Conversation

@zac-nixon

Copy link
Copy Markdown
Contributor

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Fixes #

Does this PR introduce a user-facing change?:


@k8s-ci-robot

Copy link
Copy Markdown
Contributor

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. kind/gep PRs related to Gateway Enhancement Proposal(GEP) labels Mar 31, 2026
@k8s-ci-robot k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Mar 31, 2026
Comment thread geps/gep-2645/metadata.yaml Resolved
Comment thread geps/gep-2645/metadata.yaml Resolved
Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md

// UDPRouteSpec defines the desired state of UDPRoute.
type UDPRouteSpec struct {
CommonRouteSpec `json:",inline"`

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 can't remember the full discussion of it, and I guess this also happened during Kubecon/EGADS, but I guess we need a different parentRef semantic for TCP and UDP routes, where we enforce it must be attached to a named listener, so you know which port will be routing to it.

@rostislavbobo @youngnick I need some help here, as I don't know what was the conclusion of TCP and UDPRoute

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.

I'd be interesting to hear why. A common use-case for Layer 4 load balancers is to listen on a range of ports and forward to the same backend.

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.

well, you still need a well defined port for it, right? So it means you need each port defined on the listener today, being named and then you need to select one by one which you want to attach to the same backends.

Makes me think that we also do not quite support port ranges on listeners today, but that's another story

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.

The use-case that we're making hard is that suppose I expose my application on a range of ports, 80-100, I would need to parent ref each individual port. What would be the reason to make this use-case harder?

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.

right, true. But I still have the feeling I am missing a reason why we do not do this, so I will defer to @youngnick because he may remember better than me!

Anyway, given this is provisional and eventually experimental, it is not a hard block but probably a "Must decide" situation for me

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.

anyway, should we consider a support for a port range on a listener and attachment to that listener directly? I am still thinking that for the range case you may need:

  • one listener per port on your range
  • then one parentRef for each port

even if we lower the second bar, the first one still is necessary and may be problematic, wdyt?

@youngnick youngnick Apr 20, 2026 •

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.

As it stands today, each Listener supports only one port. We have discussed port range semantics in the past, but nothing moved forward.

I think it's probably fine to say, for now:

UDPRoutes will attach to:

  • a single listener with a matching name if sectionName is supplied in the parentRef
  • a single listener with a matching port if port is supplied in the parentRef, and the implementation supports the GatewayParentRefPort feature (I think that's the right feature name)
  • All Listeners on the Gateway with protocol set to UDP if no sectionName or port is specified.

That handles the multiple ports case for now, until we decide if and how we would add port range support to Listener. (I expect there to be more appetite for that once UDPRoute and TCPRoute move forward). That would make port range on Listener semantic sugar for having that many Listener entries, one for each distinct port. I'd also recommend that port ranges must be contiguous.

But again, we should wait and handle the simpler, single-port case first, and then come back and figure out how to handle the more complex case once we have that done.

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.

I like the semantics you laid out, @youngnick as that matches the correct behavior for listener attachment.

Comment thread geps/gep-2645/index.md Resolved
Comment thread geps/gep-2645/index.md Outdated
port: 53
```

## Conformance

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 would like to have the conformance tests added on a more descriptive way. I know this is a draft for now, so leaving it as a comment for once we decide to move on.

As an example: https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-1713/index.md?plain=1#L989

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.

Yeah, I will add more detail on the conformance tests once we're happy with the UDPRoute requirements. For example, you mentioned removing weighted routing which will be important to finalize before writing conformance tests.

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.

Added more detailed conformance tests.

@rikatz

rikatz commented Mar 31, 2026

Copy link
Copy Markdown
Member

/cc
/assign

@youngnick

Copy link
Copy Markdown
Contributor

/cc

@k8s-ci-robot
k8s-ci-robot requested a review from youngnick April 1, 2026 03:10
Comment thread geps/gep-2645/index.md Outdated
#### Basic UDP Service Routing (DNS)

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

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.

we might update it to gateway.networking.k8s.io/v1
opened #4722

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.

Is the GEP for the current state or for the desired state?

@cnvergence cnvergence Apr 8, 2026 •

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 would say both, for the factual state

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.

I don't know how to represent both states. Are you suggesting duplicating the YAMLs?

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.

It is really a nit comment, the gateway resource has been GA since the Gateway API v1.0 release and should use gateway.networking.k8s.io/v1. I have found that the examples in the conformance were outdated, so we have updated them.
Thanks 🙂

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.

we must keep the GEP on the current state. We move the APIs versioning to the right state once the API is promoted.

That said:

  • Any reference to a Gateway/GatewayClass must use apiVersion v1 (the latest GA)
  • Any reference to a UDPRoute must use the current apiVersion (v1alpha2)

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.

Normally I would say that Provisional GEPS shouldn't include API details at all, but these grandfathered cases are special. I would say that right now we should document the current state. The update to v1 would, I think, normally wait for the move to Standard – but again, for these weird grandfathered cases, I'd be open to considering it in the move to Experimental (though others may not be).

Comment thread geps/gep-2645/index.md Resolved
@zac-nixon
zac-nixon force-pushed the main branch 2 times, most recently from 229531d to 9aadc8d Compare April 13, 2026 17:30
Comment thread geps/gep-2645/index.md
parentRefs:
- name: dns-gateway
sectionName: dns-udp
rules:

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.

maybe add some example on how you envision the "port range" case mentioned above

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.

This can probably hold until the discussion of how we handle port ranges on the Listener. I should note here that Service does not have port range support that I can see, so we'll need to manage that somehow as well.

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.

Will hold off on port range

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.

I suppose that the user would need to manually specify the ports in the Gateway, but we can save them the headache of duplicating the parent refs :) ideally -- it would be nice to support a range concept in the Gateway.

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 22, 2026
@k8s-ci-robot
k8s-ci-robot requested a review from snorwin April 22, 2026 00:23
Comment thread geps/gep-2645/index.md Outdated

- UDP flows are sent to port 7777 is distributed across backends respecting the configured weights (approximately 70% to `game-server-1` and 30% to `game-server-2`).

Conformance Level: **Core**

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" this is extended, given you may want to support Gateway but not UDP, but Nick knows those definitions much much better!

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.

I concur: this must be Extended conformance or it's a breaking change that requires anyone in the ecosystem who doesn't to UDP to add it.

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.

Yes, this must be Extended, with a feature name. Practically, it requires the session-tracking thing as well to produce results that don't just look like packet loss to each individual backend. The lack of connections makes a lot of things that Just Work for TCP-based protocols much harder to do, unless your interactions fit within a single UDP packet (which would be pretty unusual).

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.

A better way to say this is: Because UDP is connectionless, you can't talk about UDP "flows" without pseudo-connection state tracking. So weighted LB won't work without it.

Comment thread geps/gep-2645/index.md Outdated

## References

- [TCPRoute Specification](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute)

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.

@rikatz

rikatz commented Apr 22, 2026

Copy link
Copy Markdown
Member

overall this lgtm, thanks @zac-nixon

I will have some sync with Nick on it soon and we will bring back some more feedback.

@kflynn kflynn moved this to Needs sponsors in Gateway API - Next Experimental Apr 23, 2026
@kflynn kflynn changed the title add UDPRoute GEP EXP: UDPRoute Apr 23, 2026
@rikatz

rikatz commented Apr 23, 2026

Copy link
Copy Markdown
Member

Discussed this with Nick yesterday, this lgtm to move to provisional

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 23, 2026
@kflynn

kflynn commented Apr 29, 2026

Copy link
Copy Markdown
Contributor

I made some minor comments, but I'd be OK landing this as Provisional – nothing I said can't wait for Experimental.

/lgtm

Comment thread geps/gep-2645/index.md
Comment on lines +313 to +329
1. UDPRoute attaches to all UDP listeners in a Gateway when sectionName and port are omitted
- A Gateway has multiple UDP listeners: `dns` on port 5300 and `game` on port 7777
- A UDPRoute specifies a `parentRef` with only the Gateway name (no `sectionName` or `port`)

- The UDPRoute is accepted with the following status:

```
parents:
- parentRef:
group: gateway.networking.k8s.io
kind: Gateway
name: udp-gateway
conditions:
- type: Accepted
status: "True"
reason: Accepted
```

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.

I agree this is correct, but it might be worth pointing out that, because there's only one port in the backend reference, UDP traffic to both of those ports will end up at the same port on the backend. So, in this example, dns and game traffic would both end up at the same port on the backend, and the backend would need to be able to deal with that.

We could also just note this down as something to clarify or expand on before Experimental.

@youngnick youngnick left a comment

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.

Couple of small comments, but I think once the weighting is changed to Extended, this LGTM for Provisional for me as well.

@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 1, 2026
@zac-nixon

Copy link
Copy Markdown
Contributor Author

Moved Conformance from Core -> Extended

@rikatz

rikatz commented May 2, 2026

Copy link
Copy Markdown
Member

/hold cancel
/approve
/lgtm

This is good for provisional and then move to experimental, thanks @zac-nixon

@k8s-ci-robot k8s-ci-robot added lgtm "Looks good to me", indicates that a PR is ready to be merged. and removed do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels May 2, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rikatz, zac-nixon

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

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 2, 2026
@k8s-ci-robot
k8s-ci-robot merged commit d8e7609 into kubernetes-sigs:main May 2, 2026
20 checks passed
@github-project-automation github-project-automation Bot moved this from Needs sponsors to Done in Gateway API - Next Experimental May 2, 2026
@kflynn kflynn moved this from Done to Needs documentation in Gateway API - Next Experimental May 15, 2026
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. kind/gep PRs related to Gateway Enhancement Proposal(GEP) lgtm "Looks good to me", indicates that a PR is ready to be merged. release-note-none Denotes a PR that doesn't merit a release note. 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