Portable Traffic Manipulation with HTTPRoute Filters

When routing traffic, you often need to do more than match a path and forward the request unchanged. You might want to strip a path prefix before the request reaches the backend, redirect HTTP requests to HTTPS, or inject a header the backend expects. With the old Ingress resource, these behaviors were configured through controller-specific annotations like nginx.ingress.kubernetes.io/rewrite-target. Those annotations were not portable: a manifest written for nginx did not work on a different controller without rewriting every annotation.

Gateway API solves this by moving these behaviors into the HTTPRoute spec itself, as filters. Filters are part of the standard Kubernetes Gateway API, which means they work the same way regardless of which controller implements the Gateway underneath.

URL Rewrite: Strip a Path Prefix

A common pattern is to host a service at a sub-path of your domain, like /api, while the service itself expects requests at the root /. A client requesting /api/users should arrive at the backend as /users. The URLRewrite filter with a ReplacePrefixMatch handles this precisely.

Start with a basic HTTPRoute:

nano api-route.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-route
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - 'api.myapp.com'
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: api-svc
          port: 80

Now add the URLRewrite filter to the rule to strip the /api prefix before forwarding:

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /

The ReplacePrefixMatch replaces the matched prefix (/api) with the given value (/), so /api/users becomes /users at the backend, and /api/products/42 becomes /products/42.

kubectl apply -f api-route.yaml
kubectl describe httproute api-route

The Spec.Rules section in the describe output lists all active filters, confirming the rewrite is registered.

Request Redirect: Send the Client Elsewhere

The RequestRedirect filter does not forward the request to a backend. Instead, it sends an HTTP redirect response back to the client, telling it to re-request at a different URL. This is useful for redirecting plain HTTP traffic to HTTPS, or moving an old path permanently to a new location.

Add a redirect rule that sends HTTP clients to HTTPS:

nano redirect-route.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect-route
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
      sectionName: http
  hostnames:
    - 'api.myapp.com'
  rules:
    - filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301

This rule has no matches block, so it matches all requests arriving at the HTTP listener for api.myapp.com. It returns a 301 Moved Permanently response, instructing the client to resend the request over HTTPS.

kubectl apply -f redirect-route.yaml

Request Header Modifier: Add or Remove Headers

The RequestHeaderModifier filter lets you add, set, or remove HTTP headers before the request reaches the backend. This is useful for injecting metadata headers, removing sensitive forwarded headers, or setting values that backend services depend on.

Add a filter to the existing api-route:

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      add:
        - name: X-Gateway-Version
          value: 'v1'
      remove:
        - X-Internal-Token

The add list appends a header if it does not already exist, or adds a new value alongside existing ones. The remove list strips the named headers entirely before the request reaches the backend. Apply the updated manifest and inspect the result:

kubectl apply -f api-route.yaml
kubectl describe httproute api-route

HTTPRoute filters replace the annotation-driven customization of the old Ingress resource with a portable, spec-driven model. URL rewrites, redirects, and header manipulation are all declared within the HTTPRoute itself, which means the same manifest works on any conformant Gateway API controller and can be reviewed, tested, and versioned like any other Kubernetes resource.