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:

// HTTPPathModifierType defines the type of path redirect.
type HTTPPathModifierType string

const (
  // This type of modifier indicates that the complete path will be replaced by
  // the path redirect value.
  AbsoluteHTTPPathModifier HTTPPathModifierType = "Absolute"

  // This type of modifier indicates that any prefix path matches will be
  // replaced by the substitution value. For example, a path with a prefix match
  // of "/foo" and a ReplacePrefixMatch substitution of "/bar" will have the
  // "/foo" prefix replaced with "/bar" in matching requests.
  PrefixMatchHTTPPathModifier HTTPPathModifierType = "ReplacePrefixMatch"
)

// HTTPPathModifier defines configuration for path modifiers.
type HTTPPathModifier struct {
  // Type defines the type of path modifier.
  //
  // +kubebuilder:validation:Enum=Absolute;ReplacePrefixMatch
  Type HTTPPathModifierType `json:"type"`

  // Substitution defines the HTTP path value to substitute. An empty value ("")
  // indicates that the portion of the path to be changed should be removed from
  // the resulting path. For example, a request to "/foo/bar" with a prefix
  // match of "/foo" would be modified to "/bar".
  //
  // +kubebuilder:validation:MaxLength=1024
  Substitution string `json:"substitution"`
}

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.

kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  name: http-filter-1
spec:
  rules:
    - matches:
      - path:
          type: Prefix
          value: /foo
      filters:
      - type: RequestRedirect
        requestRedirect:
          hostname: foo.com
          path:
            type: ReplacePrefixMatch
            value: /bar

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

// HTTPRequestRedirect defines a filter that redirects a request. At most one of
// these filters may be used on a Route rule. This may not be used on the same
// Route rule as a HTTPRequestRewrite filter.
//
// Support: Extended
type HTTPRequestRedirect struct {
  // Path defines a path redirect.
  //
  // Support: Extended
  //
  // +optional
  Path *HTTPPathModifier `json:"path,omitempty"`
  // ...
}

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.

kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  name: http-filter-1
spec:
  hostnames:
  - example.com
  rules:
    - matches:
      - path:
          type: Prefix
          value: /foo
      filters:
      - type: URLRewrite
        requestRewrite:
          hostname: example.net
          path:
            type: ReplacePrefixMatch
            substitution: /bar

This would be represent with the following API additions:

// HTTPURLRewrite defines a filter that modifies a request during forwarding.
// At most one of these filters may be used on a Route rule. This may not be
// used on the same Route rule as a HTTPRequestRedirect filter.
//
// Support: Extended
type HTTPURLRewrite struct {
  // Hostname is the value to be used to replace the Host header value during
  // forwarding.
  //
  // Support: Extended
  //
  // +optional
  // +kubebuilder:validation:MaxLength=255
  Hostname *string `json:"hostname,omitempty"`

  // Path defines a path rewrite.
  //
  // Support: Extended
  //
  // +optional
  Path *HTTPPathModifier `json:"path,omitempty"`
}

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:

filters:
- type: RequestRewrite
  requestRewrite:
    path:
      type: ReplacePrefix
      pattern: /foo
      substitution: /bar

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

filters:
- type: RequestRewrite
  requestRewrite:
    path:
      type: RegularExpression
      pattern: /foo/(.*)/baz
      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:

requestRewrite:
  hostname: foo.com
  path:
    type: Prefix
    substitution: /bar

After:

requestRewrite:
  hostname: foo.com
  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:

• #200: Add support for configurable HTTP redirects
• #678: Add support for HTTP rewrites