GEP-726: Add Path Redirects and Rewrites

  • Issue: #726
  • Status: Standard

TLDR

This GEP proposes adding support for path redirects and rewrites in addition to host rewrites. This would augment the existing host redirection capabilities.

Goals

  • Implement path redirects.
  • Implement the most portable and simple forms of path rewrites.
  • Describe how more advanced rewrite and redirect and redirect capabilities could be added in the future.

API

Although many implementations support very advanced rewrite and redirect capabilities, the following are the most portable concepts that are not already supported by the Gateway API:

  • Path redirects
  • Path prefix redirects
  • Path prefix rewrites
  • Host rewrites

Although regular expression based redirects and rewrites are commonly supported, there is significantly more variation in both if and how they are implemented. Given the wide support for this concept, it is important to design the API in a way that would make it easy to add this capability in the future.

Path Modifiers

Both redirects and rewrites would share the same PathModifier types:

  1. // HTTPPathModifierType defines the type of path redirect.
  2. type HTTPPathModifierType string
  4. const (
  5.   // This type of modifier indicates that the complete path will be replaced by
  6.   // the path redirect value.
  7.   AbsoluteHTTPPathModifier HTTPPathModifierType = "Absolute"
  9.   // This type of modifier indicates that any prefix path matches will be
  10.   // replaced by the substitution value. For example, a path with a prefix match
  11.   // of "/foo" and a ReplacePrefixMatch substitution of "/bar" will have the
  12.   // "/foo" prefix replaced with "/bar" in matching requests.
  13.   PrefixMatchHTTPPathModifier HTTPPathModifierType = "ReplacePrefixMatch"
  14. )
  16. // HTTPPathModifier defines configuration for path modifiers.
  17. type HTTPPathModifier struct {
  18.   // Type defines the type of path modifier.
  19.   //
  20.   // +kubebuilder:validation:Enum=Absolute;ReplacePrefixMatch
  21.   Type HTTPPathModifierType `json:"type"`
  23.   // Substitution defines the HTTP path value to substitute. An empty value ("")
  24.   // indicates that the portion of the path to be changed should be removed from
  25.   // the resulting path. For example, a request to "/foo/bar" with a prefix
  26.   // match of "/foo" would be modified to "/bar".
  27.   //
  28.   // +kubebuilder:validation:MaxLength=1024
  29.   Substitution string `json:"substitution"`
  30. }

Redirects

The existing RequestRedirect filter can be expanded to support path redirects. In the following example, a request to /foo/abc would be redirected to /bar/abc.

  1. kind: HTTPRoute
  2. apiVersion: gateway.networking.k8s.io/v1alpha2
  3. metadata:
  4.   name: http-filter-1
  5. spec:
  6.   rules:
  7.     - matches:
  8.       - path:
  9.           type: Prefix
  10.           value: /foo
  11.       filters:
  12.       - type: RequestRedirect
  13.         requestRedirect:
  14.           hostname: foo.com
  15.           path:
  16.             type: ReplacePrefixMatch
  17.             value: /bar

This would be represented with the following API addition to the existing HTTPRequestRedirect filter:

  1. // HTTPRequestRedirect defines a filter that redirects a request. At most one of
  2. // these filters may be used on a Route rule. This may not be used on the same
  3. // Route rule as a HTTPRequestRewrite filter.
  4. //
  5. // Support: Extended
  6. type HTTPRequestRedirect struct {
  7.   // Path defines a path redirect.
  8.   //
  9.   // Support: Extended
  10.   //
  11.   // +optional
  12.   Path *HTTPPathModifier `json:"path,omitempty"`
  13.   // ...
  14. }

Rewrites

A new URLRewrite filter can be added to support rewrites. In the following example, a request to example.com/foo/abc would be rewritten to example.net/bar/abc.

  1. kind: HTTPRoute
  2. apiVersion: gateway.networking.k8s.io/v1alpha2
  3. metadata:
  4.   name: http-filter-1
  5. spec:
  6.   hostnames:
  7.   - example.com
  8.   rules:
  9.     - matches:
  10.       - path:
  11.           type: Prefix
  12.           value: /foo
  13.       filters:
  14.       - type: URLRewrite
  15.         requestRewrite:
  16.           hostname: example.net
  17.           path:
  18.             type: ReplacePrefixMatch
  19.             substitution: /bar

This would be represent with the following API additions:

  1. // HTTPURLRewrite defines a filter that modifies a request during forwarding.
  2. // At most one of these filters may be used on a Route rule. This may not be
  3. // used on the same Route rule as a HTTPRequestRedirect filter.
  4. //
  5. // Support: Extended
  6. type HTTPURLRewrite struct {
  7.   // Hostname is the value to be used to replace the Host header value during
  8.   // forwarding.
  9.   //
  10.   // Support: Extended
  11.   //
  12.   // +optional
  13.   // +kubebuilder:validation:MaxLength=255
  14.   Hostname *string `json:"hostname,omitempty"`
  16.   // Path defines a path rewrite.
  17.   //
  18.   // Support: Extended
  19.   //
  20.   // +optional
  21.   Path *HTTPPathModifier `json:"path,omitempty"`
  22. }

Note: RequestRewrite was originally considered as a name for this filter. URLRewrite was chosen as it more clearly represented the capabilities of the filter and would not be confused with header or query param modification.

Portability

When considering what should be possible in the API, it’s worth evaluating what common tooling is capable of. This is by no means a complete list, but this provides a high level overview of how this is configured across different implementations.

Although not all of these implementations directly support prefix rewrites or redirects, the ones that don’t include regular expression support which can be used to implement prefix rewrites and redirects.

Note: This section intentionally excludes the redirect capabilities already contained in the API.

Envoy

Envoy supports the following relevant capabilities (reference):

  • path_redirect (redirect only)
  • prefix_rewrite (redirect and forwarding)
  • regex_rewrite (redirect and forwarding)
  • host_rewrite_literal (forwarding only)
  • strip_query (redirect only)

Note that path rewrite relies on the prefix match for the route, there is not a way to differentiate between the prefix used for matching and rewriting.

Google Cloud

Google Cloud URL Maps support the following relevant capabilities (reference):

  • pathPrefixRewrite (forwarding only)
  • hostRewrite (forwarding only)
  • pathRedirect (redirect only)
  • prefixRedirect (redirect only)
  • stripQuery (redirect only)

Note that path rewrite relies on the prefix match for the route, there is not a way to differentiate between the prefix used for matching and rewriting.

HAProxy

HAProxy supports the following relevant capabilities (reference):

  • http-request set-path (advanced path rewrite capabilities)
  • http-request replace-path (rewrites entire path)
  • http-request replace-pathq (rewrites entire path + query string)
  • http-request replace-uri (URI rewrite based on input regex)
  • redirect location (advanced redirect capabilities)

NGINX

The NGINX rewrite module contains the following relevant capabilities (reference):

  • PCRE regex based rewrites
  • Rewrite directive can be used during forwarding or redirects
  • Rewrite directive can affect host, path, or both
  • Rewrite directive can be chained

Future Extension

There are two relatively common types of path rewrite/redirect that are not covered by this proposal:

  1. Replace a path prefix separate from the match
  2. Replace with a Regular Expression substitution

Both of the following can be represented by adding a new field new types. For example, this config would result in a request to /foo/baz to be rewritten to /bar/baz:

  1. filters:
  2. - type: RequestRewrite
  3.   requestRewrite:
  4.     path:
  5.       type: ReplacePrefix
  6.       pattern: /foo
  7.       substitution: /bar

Similarly, this config would result in a request to /foo/bar/baz being rewritten to /foo/other/baz.

  1. filters:
  2. - type: RequestRewrite
  3.   requestRewrite:
  4.     path:
  5.       type: RegularExpression
  6.       pattern: /foo/(.*)/baz
  7.       substitution: other

Although both of the above are natural extensions of the API, they are not quite as broadly supported. For that reason, this GEP proposes omitting these types from the initial implementation.

Alternatives

1. Generic Path Match Replacement

Instead of the ReplacePrefixMatch option proposed above, we could have a ReplacePathMatch option. This would provide significantly more flexibility and room for growth than prefix replacement.

Unfortunately it would be difficult to represent conformance and support levels. It also would have limited value. Replacing “Exact” match types would be nearly identical to the “Absolute” match type, and replacing “RegularExpression” match types would likely not yield the desired result. In most cases, RegEx rewrites are implemented separately from RegEx path matching. So a user may want to match all paths matching one RegEx, but use a separate RegEx + substitution value for rewrites.

It is theoretically possible that future patch match types could be useful as a rewrite source, but the common proxies described above seem to be limited to the rewrite types described above.

2. Top Level Rewrite Fields

Although a small difference, we could restructure how the path rewrites and redirects were configured. One example would be adding top level fields in the filters for each kind of path rewrite or redirect. That would result in a change like this:

Before:

  1. requestRewrite:
  2.   hostname: foo.com
  3.   path:
  4.     type: Prefix
  5.     substitution: /bar

After:

  1. requestRewrite:
  2.   hostname: foo.com
  3.   pathPrefix: /bar

Although simpler for the initial use cases, it may become more difficult to maintain and validate as additional types of rewrites and redirects were added.

References

Issues: