Skip to content

HTTP path redirects and rewrites

HTTPRoute resources can issue redirects to clients or rewrite paths sent upstream using filters. This guide shows how to use these features.

Note that redirect and rewrite filters are mutually incompatible. Rules cannot use both filter types at once.

Redirects

Redirects return HTTP 3XX responses to a client, instructing it to retrive a different resource. RequestRedirect rule filters instruct Gateways to emit a redirect response to requests matching a filtered HTTPRoute rule.

Redirect filters can substitute various URL components independently. For example, to issue a permanent redirect (301) from HTTP to HTTPS, configure requestRedirect.statusCode=301 and requestRedirect.scheme="https":

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  hostnames:
    - redirect.example
  rules:
    - filters:
      - type: RequestRedirect
        requestRedirect:
          scheme: https
          statusCode: 301
      backendRefs:
      - name: example-svc
        weight: 1
        port: 80

Redirects change configured URL components to match the redirect configuration while preserving other components from the original request URL. In this example, the request GET http://redirect.example/cinammon will result in a 301 response with a location: https://redirect.example/cinnamon header. The hostname (redirect.example), path (/cinnamon), and port (implicit) remain unchanged.

Path redirects

Experimental Channel

The Path field described below is currently only included in the "Experimental" channel of Gateway API. For more information on release channels, refer to the related documentation.

Path redirects use an HTTP Path Modifier to replace either entire paths or path prefixes. For example, the HTTPRoute below will issue a 302 redirect to all redirect.example requests whose path begins with /cayenne to /paprika:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  hostnames:
    - redirect.example
  rules:
    - matches:
      - path:
          type: PathPrefix
          value: /cayenne
      filters:
      - type: RequestRedirect
        requestRedirect:
          path:
            type: ReplaceFullPath
            replaceFullPath: /paprika
          statusCode: 302
      backendRefs:
      - name: example-svc
        weight: 1
        port: 80

Both requests to https://redirect.example/cayenne/pinch and https://redirect.example/cayenne/teaspoon will receive a redirect with a location: https://redirect.example/paprika.

The other path redirect type, ReplacePrefixMatch, replaces only the path portion matching matches.path.value. Changing the filter in the above to:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  hostnames:
    - redirect.example
  rules:
    - matches:
      - path:
          type: PathPrefix
          value: /cayenne
      filters:
      - type: RequestRedirect
        requestRedirect:
          path:
            type: ReplacePrefixMatch
            replacePrefixMatch: /paprika
          statusCode: 302
      backendRefs:
      - name: example-svc
        weight: 1
        port: 80

will result in redirects with location: https://redirect.example/paprika/pinch and location: https://redirect.example/paprika/teaspoon response headers.

Rewrites

Experimental Channel

The URLRewrite filter described below is currently only included in the "Experimental" channel of Gateway API. For more information on release channels, refer to the related documentation.

Rewrites modify components of a client request before proxying it upstream. A URLRewrite filter can change the upstream request hostname and/or path. For example, the following HTTPRoute will accept a request for https://rewrite.example/cardamom and send it upstream to example-svc with host: elsewhere.example in request headers instead of host: rewrite.example.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-filter-rewrite
spec:
  hostnames:
    - rewrite.example
  rules:
    - filters:
      - type: URLRewrite
        urlRewrite:
          hostname: elsewhere.example
      backendRefs:
      - name: example-svc
        weight: 1
        port: 80

Path rewrites also make use of HTTP Path Modifiers. The HTTPRoute below will take request for https://rewrite.example/cardamom/smidgen and proxy a request to https://elsewhere.example/fennel upstream to example-svc. Instead using type: ReplacePrefixMatch and replacePrefixMatch: /fennel will request https://elsewhere.example/fennel/smidgen upstream.

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: http-filter-rewrite
spec:
  hostnames:
    - rewrite.example
  rules:
    - filters:
      - type: URLRewrite
        urlRewrite:
          hostname: elsewhere.example
      backendRefs:
      - name: example-svc
        weight: 1
        port: 80
Back to top