GEP for regex-based path rewrites: initial commit #4361

muxanasov · 2025-12-17T17:08:57Z

What type of PR is this?
/kind documentation

What this PR does / why we need it:
This is to create a new GEP

Does this PR introduce a user-facing change?:
No

linux-foundation-easycla · 2025-12-17T17:09:03Z

The committers listed above are authorized under a signed CLA.

✅ login: muxanasov / name: Mikhail Afanasov (060d3d5, 24e1e14, f8b0bec, 4ed6537)

k8s-ci-robot · 2025-12-17T17:09:06Z

Welcome @muxanasov!

It looks like this is your first PR to kubernetes-sigs/gateway-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/gateway-api has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-12-17T17:09:07Z

Hi @muxanasov. Thanks for your PR.

I'm waiting for a github.com member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

robscott

Thanks @muxanasov!

robscott · 2025-12-19T06:30:43Z

geps/gep-4359/index.md

+
+## Goals
+
+Close the feature gap for Gateway API.


Instead of just closing the feature gap, I'd recommend focusing on the specific capabilities you want to express with the API, such as:

Rewrite the path of a request based on a regular expression, regardless of initial match type

Substitute matching section(s) in the regular expression with predefined values

On point 2, I'm not sure if the goal is to substitute multiple or just a single match, and how the substitution should be formatted - multiple inputs or just one?

k8s-ci-robot · 2025-12-19T09:07:35Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: muxanasov
Once this PR has been reviewed and has the lgtm label, please assign aojea 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:

geps/OWNERS

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

robscott · 2025-12-20T01:36:45Z

/release-note-none
/ok-to-test

robscott · 2025-12-20T01:38:42Z

geps/gep-4359/index.md

+
+## New Fields relationship
+
+The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.


Suggested change

The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.

The relationship between new fields should be consistent across different underlying implementations and dataplanes. The syntax, however, may vary depending on the implementation.

robscott

Thanks @muxanasov!

/cc @rikatz @kflynn @mikemorris

robscott · 2025-12-20T01:41:10Z

geps/gep-4359/index.md

+
+While relationship between pattern and substitution are invariant across implementaitons, the regex syntax is implemntation scpeific.
+
+Here we show examples that use Google's [RE2](https://github.com/google/re2) engine and should work in Envoy's [regex_rewrite](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-regex-rewrite).


When you write a conformance test plan, I'd recommend suggesting that we find a way to configure the regex format, and then ensuring that the conformance tests are written in a way that they can support multiple formats. We could start with RE2, but it should be possible to plug in other formats.

robscott · 2025-12-20T01:41:53Z

geps/gep-4359/index.md

+  hostnames:
+  - "*"


Nit: I'd recommend leaving this out as it's implied.

robscott · 2025-12-20T01:42:36Z

geps/gep-4359/index.md

+
+This GEP proposes the following API changes:
+
+* Update [httproute_types.go](https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1beta1/httproute_types.go) by adding and new `HTTPRegexModifier` field


Suggested change

* Update [httproute_types.go](https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1beta1/httproute_types.go) by adding and new `HTTPRegexModifier` field

* Update [httproute_types.go](https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1beta1/httproute_types.go) by adding a new `HTTPRegexModifier` field

robscott · 2025-12-20T01:43:41Z

geps/gep-4359/index.md

+Close the regex-based path rewrites feature gap for Gateway API, i.e.:
+ * Rewrite the path of a request based on a regular expression, regardless of initial match type


Sadly our docs generator requires a new line before lists like this:

Suggested change

Close the regex-based path rewrites feature gap for Gateway API, i.e.:

* Rewrite the path of a request based on a regular expression, regardless of initial match type

Close the regex-based path rewrites feature gap for Gateway API, i.e.:

* Rewrite the path of a request based on a regular expression, regardless of initial match type

rikatz · 2025-12-22T18:32:28Z

geps/gep-4359/index.md

+
+The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.
+
+* `pathPattern` The regular expression used to find portions of a string (hereafter called the “subject string”) that should be replaced. When a new string is produced during the substitution operation, the new string is initially the same as the subject string, but then all matches in the subject string are replaced by the substitution string. If replacing all matches isn’t desired, regular expression anchors can be used to ensure a single match, so as to replace just one occurrence of a pattern. Capture groups can be used in the pattern to extract portions of the subject string, and then referenced in the substitution string.


Suggested change

* `pathPattern` The regular expression used to find portions of a string (hereafter called the “subject string”) that should be replaced. When a new string is produced during the substitution operation, the new string is initially the same as the subject string, but then all matches in the subject string are replaced by the substitution string. If replacing all matches isn’t desired, regular expression anchors can be used to ensure a single match, so as to replace just one occurrence of a pattern. Capture groups can be used in the pattern to extract portions of the subject string, and then referenced in the substitution string.

* `pathPattern` The regular expression used to find portions of a string (hereafter called the `subject string`) that should be replaced. When a new string is produced during the substitution operation, the new string is initially the same as the subject string, but then all matches in the subject string are replaced by the substitution string. If replacing all matches isn’t desired, regular expression anchors can be used to ensure a single match, so as to replace just one occurrence of a pattern. Capture groups can be used in the pattern to extract portions of the subject string, and then referenced in the substitution string.

rikatz · 2025-12-22T18:36:26Z

geps/gep-4359/metadata.yaml

+relationships:
+  seeAlso:
+    - https://gateway-api.sigs.k8s.io/geps/gep-726/#future-extension
+references:


can you also add the references of nginx and haproxy here so we can keep it more agnostic? thanks! :D

rikatz · 2025-12-22T18:52:31Z

Hi @muxanasov and thanks for the proposal!

I agree this is a very important feature to get people moving to Gateway API, I would just like to put my "ingress-nginx former maintainer" hat a bit: having regexes as part of the API can be very very complex (and somehow dangerous):

the Regex parser used by Envoy (re2) is different from NGINX (PCRE) and can even be different from other implementations that may be pure Go or pure Rust, or even on different technologies. So it would be a bit "hard" to define conformance, if each implementation behaves on a different way.
Because the subset of regex characters that can be used on an API field is big, and because eventually these characters may end up on a proxy configuration file (eg.: NGINX or HAProxy), we need to be really careful with what characters we would allow. We won't be able to do any validation on the API side, because we will be able to only limit the characters for non-characters control but not really define if that is a valid regex. So it is a wide open arbitrary API field
On some cases, IIRC a regex can be used for internal redirects, that may lead to users pointing to internal non-exposed endpoints. This is a bit risky

That said, I think we do need some feature like this, but if possible I would like to try to scope it to:

Can we define a minimum regex set that is acceptable by all the parsers, with a minimum set of characters? (eg.: can we define what is the acceptable set of characters that we could validate?)
Should this be "Implementation Specific", given each implementation may have its own way of parsing a regex?
Is there any "user story" of regexes that could actually be covered by a lack of some other API that would be more strict?

Thanks again for the proposal!

howardjohn

Overall in favor of the direction but I think the API itself could use a few tweaks

howardjohn · 2025-12-22T18:58:22Z

geps/gep-4359/index.md

+	// Support: Extended
+	//
+	// +optional
+	RegexModifier *HTTPRegexModifier `json:"regexModifier,omitempty"`


just nitpicking on field names here.

This seems a bit odd. It says its about path OR host, but it only has path. Maybe the intent was to add hostPattern and hostSubstitute in the future, but that is somewhat awkward....

Why not adding this under HTTPPathModifier?

So

path: type: Regex regex: match: blah substitution: blah

this seems more consistent with the existing API

howardjohn · 2025-12-22T18:58:38Z

geps/gep-4359/index.md

+  // +optional
+  // +kubebuilder:validation:Minimum=0
+  // +kubebuilder:validation:Maximum=1024
+	PathPattern *string `json:"pathPattern,omitempty"`


not required for the GEP but we really really need some examples here for users

And details on the matching semantics. Is it a full string match or substring? Should it match the leading /?

howardjohn · 2025-12-22T19:01:15Z

geps/gep-4359/index.md

+    filters:
+      - type: URLRewrite
+        urlRewrite:
+          regexModifier:


I am not sure this is a good idea but wanted to mention it.

Given regex is implementation specific, and even more so with capture groups, do we event want to bother tying this to regex?

For example, an implementation could support:

pattern: /region/{region}/bucket/{storage}/{object}.pdf substitution: /{region}/bucket-{storage}/{object}.pdf

which is not regex but fulfills the same purpose (not saying we make that syntax part of the spec, just that if we remove "regex" to "pattern" we could enable it)

k8s-ci-robot added the do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. label Dec 17, 2025

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Dec 17, 2025

k8s-ci-robot requested review from candita and robscott December 17, 2025 17:09

k8s-ci-robot added the kind/gep PRs related to Gateway Enhancement Proposal(GEP) label Dec 17, 2025

k8s-ci-robot added cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Dec 17, 2025

muxanasov force-pushed the main branch from 24d8660 to 98fbd53 Compare December 17, 2025 17:30

robscott reviewed Dec 19, 2025

View reviewed changes

k8s-ci-robot added do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Dec 19, 2025

muxanasov and others added 2 commits December 19, 2025 09:05

GEP for regex-based path rewrites: initial commit

f8b0bec

Small fixes in GEP

4ed6537

muxanasov force-pushed the main branch from a8ebf4d to 4ed6537 Compare December 19, 2025 09:07

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Dec 19, 2025

muxanasov added 2 commits December 19, 2025 09:18

Addressing review comments

060d3d5

Added more details to the API description and examples

24e1e14

muxanasov requested a review from robscott December 19, 2025 09:39

robscott reviewed Dec 20, 2025

View reviewed changes

k8s-ci-robot requested review from kflynn, mikemorris and rikatz December 20, 2025 01:44

rikatz reviewed Dec 22, 2025

View reviewed changes

howardjohn reviewed Dec 22, 2025

View reviewed changes


		## New Fields relationship

		The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.

	The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.
	The relationship between new fields should be consistent across different underlying implementations and dataplanes. The syntax, however, may vary depending on the implementation.


		While relationship between pattern and substitution are invariant across implementaitons, the regex syntax is implemntation scpeific.

		Here we show examples that use Google's [RE2](https://github.com/google/re2) engine and should work in Envoy's [regex_rewrite](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-regex-rewrite).


		This GEP proposes the following API changes:

		* Update [httproute_types.go](https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1beta1/httproute_types.go) by adding and new `HTTPRegexModifier` field

		Close the regex-based path rewrites feature gap for Gateway API, i.e.:
		* Rewrite the path of a request based on a regular expression, regardless of initial match type


		The relationship between new fields shluld stay invartiant across different underlying implementaions and dataplanes. The syntax, however, may vary depending on the implementation.

		* `pathPattern` The regular expression used to find portions of a string (hereafter called the “subject string”) that should be replaced. When a new string is produced during the substitution operation, the new string is initially the same as the subject string, but then all matches in the subject string are replaced by the substitution string. If replacing all matches isn’t desired, regular expression anchors can be used to ensure a single match, so as to replace just one occurrence of a pattern. Capture groups can be used in the pattern to extract portions of the subject string, and then referenced in the substitution string.

GEP for regex-based path rewrites: initial commit #4361

Are you sure you want to change the base?

GEP for regex-based path rewrites: initial commit #4361

Conversation

muxanasov commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Dec 17, 2025

Uh oh!

k8s-ci-robot commented Dec 17, 2025

Uh oh!

robscott left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Dec 19, 2025

Uh oh!

robscott commented Dec 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

rikatz Dec 22, 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!

rikatz commented Dec 22, 2025

Uh oh!

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

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

muxanasov commented Dec 17, 2025 •

edited

Loading

linux-foundation-easycla bot commented Dec 17, 2025 •

edited

Loading

rikatz Dec 22, 2025 •

edited

Loading