Skip to content

Regex in Gateway API - #4764

Merged
kubernetes-prow[bot] merged 24 commits into
kubernetes-sigs:mainfrom
Stevenjin8:regex
Aug 11, 2026
Merged

kubernetes-prow[bot] merged 24 commits into
kubernetes-sigs:mainfrom
Stevenjin8:regex

Conversation

@Stevenjin8

@Stevenjin8 Stevenjin8 commented Apr 17, 2026 •

Copy link
Copy Markdown
Contributor

/kind test

What this PR does / why we need it:

This defines a common regex denominator so we can progress on other GEPs that require regex (regex path rewrites)

Preliminary GEP for Gateway API Regex

@k8s-ci-robot k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. kind/test do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. labels Apr 17, 2026
@k8s-ci-robot

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

The full list of commands accepted by this bot can be found 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 requested a review from kl52752 April 17, 2026 16:38
@k8s-ci-robot k8s-ci-robot added kind/gep PRs related to Gateway Enhancement Proposal(GEP) 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 Apr 17, 2026
@rikatz

rikatz commented Apr 17, 2026

Copy link
Copy Markdown
Member

/remove-kind test

@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.

I think this is a great idea, but I think there are some other things I think we should talk about:

  • We need to be clear if this is a minimum set of features, or a maximum. What happens if the regex uses characters outside these standards? Is that ImplementationSpecific? How should an implementation detect non-standard Regexes, and what should they do if they don't support it? Should we consider making a specific name for this type of regex (like a non-namespaced Regex name or something), and then letting implementations add domain-prefrixed Regex types instead (like implementation.io/RegexWithExtras) or something?
  • We should lay out some general handling rules. What happens if the regex is invalid by these standards? Feels like we should say "the relevant containing structure must be considered invalid and not used for configuration", which would mean that for HTTPRoute Rules, that rule is invalid, and similarly in other places.

Comment thread geps/gep-4359/index.md Resolved
@muxanasov

Copy link
Copy Markdown
Contributor

I think this is a great idea, but I think there are some other things I think we should talk about:

  • We need to be clear if this is a minimum set of features, or a maximum. What happens if the regex uses characters outside these standards? Is that ImplementationSpecific? How should an implementation detect non-standard Regexes, and what should they do if they don't support it? Should we consider making a specific name for this type of regex (like a non-namespaced Regex name or something), and then letting implementations add domain-prefrixed Regex types instead (like implementation.io/RegexWithExtras) or something?
  • We should lay out some general handling rules. What happens if the regex is invalid by these standards? Feels like we should say "the relevant containing structure must be considered invalid and not used for configuration", which would mean that for HTTPRoute Rules, that rule is invalid, and similarly in other places.

I'd keep things simple, transparent, consistent; similar to https://gateway-api.sigs.k8s.io/reference/spec/#pathmatchtype

Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md
### Referencing Capturing Groups

In the case that referencing capturing groups is supported, APIs MUST use the `\1`, `\2`, etc. syntax in the replacement string to reference capturing groups.
Named capturing groups are not explicitly supported, and the syntax for referencing them is undefined.

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.

why?

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.

  1. I don't think the syntax is particularly standardized
  2. Named capturing groups are purely ergonomic
  3. I think its better that we start off with a limit set of supported features as this is supposed to be a common denominator.

@muxanasov muxanasov 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.

I don't have strong arguments at the moment, I just look at the possible evolution of the regex rewrite section where we can use some capture groups from request header and use them to build a new path. Agree, this is pretty niche feature, but numbered capture groups would make this scenario impossible: consider we have two patterns for each header and path, each pattern will have \1 \2 \3 capture groups - we could not distinguish the numbered groups in substitute.

I know that here we do not reject named groups, but with the possible regex rewrite evolution above, numbered capture groups might be rejected by the vendor's API.

I just don't feel like we want to standardize numbered capture groups. It might create more problems in future than it solves.

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 was actually wondering if named captures would always be accepted but not the numbered ones. I was thinking that something like this would make sense:

- regex: {protocol}://{fqdn}({port})?/{path1}/{path2}/{path3}?{arg1}&{arg2}
  replace: https://{fqdn}/{path2}/{path1}?{arg2}&something=else

mostly thinking that regexes can be "hard to define" initially, and trying to understand if the majority of user stories are just related to something like "I want to remove a path", "I want to add an extra path", "I want to inject an argument"

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'm with @Stevenjin8 on this one: I'd prefer something that can be directly passed to the engine without preprocessing, and that implies numbered groups but not named groups.

I'm not completely opposed to defining our own named-group syntax (as in @rikatz's example), but I'm not sure how valuable it'll be since it is by definition going to be a breaking change that will affect users.

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 should've phrased that last point as "it feels likely that requiring named groups will force more people to change what they do than allowing only numbered groups". As @Stevenjin8 points out, when there's no API, you can't really have a "breaking change".

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, I think I misunderstood this is a required limitation rather than required minimum. I think named groups might still remain implementation-specific, while numbered groups - minimum requirement.

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.

Remember that every time you add an implementation-specific thing, you build a migration footgun for your users.

@Stevenjin8

Copy link
Copy Markdown
Contributor Author

We need to be clear if this is a minimum set of features, or a maximum.

minimum

What happens if the regex uses characters outside these standards? Is that ImplementationSpecific? How should an implementation detect non-standard Regexes, and what should they do if they don't support it?
Should we consider making a specific name for this type of regex (like a non-namespaced Regex name or something), and then letting implementations add domain-prefrixed Regex types instead (like implementation.io/RegexWithExtras) or something?

I think there are two questions here. Validation and failure modes. Validating regexes is something I'd would rather avoid because we can't do it at an API-level. If a regex is unsupported, then the failure mode would be specified in the parent type.

My vision is that for resources across gateway api, we can have various fields of type regex, which will carry at the very least the semantics specified by this GEP. This way, we can write conformance tests for these fields (unlike our current RegularExpression path matching.

This isn't great from the POV that a user might subscribe to implementation-specific semantics by using the core API, but we already do this with all variants of path matching. For Exact and Prefix, how URL paths are normalized before matching is implementation specific (and does vary). RegularExpression path matching is completely implementation-specific.

having implementations validate Gateway API Regex might also be a bit annoying.

We should lay out some general handling rules. What happens if the regex is invalid by these standards? Feels like we should say "the relevant containing structure must be considered invalid and not used for configuration", which would mean that for HTTPRoute Rules, that rule is invalid, and similarly in other places.

Again, I'd rather avoid validation that we cannot do at the API level. Do we have non-api validation anywhere else in Gateway API?

@Stevenjin8

Copy link
Copy Markdown
Contributor Author

/retest

Comment thread geps/gep-4359/index.md Resolved
@youngnick

Copy link
Copy Markdown
Contributor

What I was trying to say is that, if "hey, if you use regex that's not described in this document, we can't guarantee that it will be portable, and may fail in unpredictable ways if it is not portable, good luck" is the position we want to take, then we need to write that down in here. That way we at least have some proof that we've discussed and agreed that that's the position we are taking.

For the record, I agree that having some set of regex functionality that is agreed on and conformance tested is better than only having ImplementationSpecific support, but having the regex support be open-ended is worrying. So, we need to record the expectations. We're not going to be able to make perfect decisions here, but we need to at least record all the consequences we can think of for the decisions we do make.

@kubernetes-prow kubernetes-prow Bot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 4, 2026
@rikatz

rikatz commented Aug 5, 2026

Copy link
Copy Markdown
Member

/lgtm

the proposal looks good to me, thanks for the clarifications and for adding the warnings

/cc @youngnick as the second reviewer

@kubernetes-prow

Copy link
Copy Markdown

@rikatz: GitHub didn't allow me to request PR reviews from the following users: the, second, reviewer, as.

Note that only kubernetes-sigs members and repo collaborators can review this PR, and authors cannot review their own PRs.

Details

In response to this:

/lgtm

the proposal looks good to me, thanks for the clarifications and for adding the warnings

/cc @youngnick as the second reviewer

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@kubernetes-prow kubernetes-prow Bot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 5, 2026
@rikatz

rikatz commented Aug 5, 2026

Copy link
Copy Markdown
Member

/cc @youngnick

Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/metadata.yaml Resolved
Comment thread geps/gep-4359/metadata.yaml Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
Comment thread geps/gep-4359/index.md Resolved
@youngnick

Copy link
Copy Markdown
Contributor

I added some suggestions that I think are important to make sure we are clear on the footguns we will hand to users whenever we use this.

There are also some formatting things.

Aside from those, I think this LGTM for merging.

@kubernetes-prow kubernetes-prow Bot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 10, 2026

@Stevenjin8 Stevenjin8 left a comment

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.

@youngnick made the edits

@youngnick

Copy link
Copy Markdown
Contributor

/approve
/lgtm

@kubernetes-prow kubernetes-prow Bot added lgtm "Looks good to me", indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Aug 11, 2026
@rikatz

rikatz commented Aug 11, 2026

Copy link
Copy Markdown
Member

/approve
/hold cancel

@kubernetes-prow kubernetes-prow Bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 11, 2026
@kubernetes-prow

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: rikatz, Stevenjin8, 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

@kubernetes-prow
kubernetes-prow Bot merged commit 28a199a into kubernetes-sigs:main Aug 11, 2026
20 checks passed
@Stevenjin8 Stevenjin8 mentioned this pull request Aug 13, 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 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.

9 participants