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 retrieve 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/v1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  parentRefs:
  - name: redirect-gateway
    sectionName: http
  hostnames:
  - redirect.example
  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

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/cinnamon 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.

HTTP-to-HTTPS redirects¶

To redirect HTTP traffic to HTTPS, you need to have a Gateway with both HTTP and HTTPS listeners.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: redirect-gateway
spec:
  gatewayClassName: foo-lb
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      mode: Terminate
      certificateRefs:
      - name: redirect-example

There are multiple ways to secure a Gateway. In this example, it is secured using a Kubernetes Secret(redirect-example in the certificateRefs section).

You need a HTTPRoute that attaches to the HTTP listener and does the redirect to HTTPS. Here we set sectionName to be http so it only selects the listener named http.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-redirect
spec:
  parentRefs:
  - name: redirect-gateway
    sectionName: http
  hostnames:
  - redirect.example
  rules:
  - filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        statusCode: 301

You also need a HTTPRoute that attaches to the HTTPS listener that forwards HTTPS traffic to application backends.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: https-route
  labels:
    gateway: redirect-gateway
spec:
  parentRefs:
  - name: redirect-gateway
    sectionName: https
  hostnames:
  - redirect.example
  rules:
  - backendRefs:
    - name: example-svc
      port: 80

Path redirects¶

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/v1
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

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/v1
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

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

Rewrites¶

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/v1
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.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-rewrite
spec:
  hostnames:
    - rewrite.example
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /cardamom
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: elsewhere.example
            path:
              type: ReplaceFullPath
              replaceFullPath: /fennel
      backendRefs:
        - name: example-svc
          weight: 1
          port: 80

Instead using type: ReplacePrefixMatch and replacePrefixMatch: /fennel will request https://elsewhere.example/fennel/smidgen upstream.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: http-filter-rewrite
spec:
  hostnames:
    - rewrite.example
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /cardamom
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: elsewhere.example
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /fennel
      backendRefs:
        - name: example-svc
          weight: 1
          port: 80