Request/Response Modifications: Filters and Rewrites

Advanced

URL Rewriting
Nginx Ingress - Rewrite Target
Gateway API - URLRewrite Filter
+36 more sections...

Request/Response Modifications: Filters and Rewrites

Gateway API provides powerful filters for modifying requests and responses. This guide covers URL rewriting, header modifications, and redirects, comparing them to Nginx Ingress equivalents.

Request/Response Modification Flow

How Gateway API modifies requests and responses using filters

Request Modification

Original Request

GET /api/v1/users

Host: example.com

X-Custom: value

Filters Applied

URL Rewrite

/api/v1/users → /users

Header Add

X-Forwarded-By: gateway

Header Remove

X-Custom: removed

Modified Request to Backend

GET /users

Host: example.com

X-Forwarded-By: gateway

Response Modification

Backend Response

Status: 200 OK

Content-Type: application/json

X-Backend-Version: v1.0

Response Filters Applied

Header Add

X-Gateway-Version: 2.0

Header Remove

X-Backend-Version: removed

Modified Response to Client

Status: 200 OK

Content-Type: application/json

X-Gateway-Version: 2.0

Available Filters

URL Rewrite

Modify request path before forwarding to backend

Header Modification

Add, remove, or modify HTTP headers in requests/responses

Redirect

Redirect requests to different URLs

Request Mirroring

Send copy of request to another backend for testing

vs. Ingress: Gateway API provides native filter support. Ingress requires Nginx annotations like nginx.ingress.kubernetes.io/rewrite-target.

URL Rewriting

URL rewriting allows you to modify the request path before forwarding to the backend.

Nginx Ingress - Rewrite Target

Nginx Ingress uses annotations for URL rewriting:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rewrite-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-service
                port:
                  number: 80

This rewrites /api/* to /* before forwarding.

Gateway API - URLRewrite Filter

Gateway API uses native filters:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: api-service
          port: 80

URLRewrite Filter Types

1. ReplacePrefixMatch

Replaces the matched path prefix:

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

Example:

Request: /api/users
Matched: /api (prefix)
Rewritten: /v2/users
Forwarded to backend: /v2/users

2. ReplaceFullPath

Replaces the entire path:

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplaceFullPath
        replaceFullPath: /new-path

Example:

Request: /api/v1/users/123
Rewritten: /new-path
Forwarded to backend: /new-path

3. ReplacePathMatch

Replaces a matched path segment:

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePathMatch
        replacePathMatch: /old
        replaceWith: /new

Common Rewrite Patterns

Pattern 1: Strip Prefix

Remove a path prefix before forwarding:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: strip-prefix-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: api-service
          port: 80

Example:

Request: /api/v1/users
Rewritten: /v1/users
Backend receives: /v1/users

Pattern 2: Add Prefix

Add a path prefix:

filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplaceFullPath
        replaceFullPath: /api/v2

Example:

Request: /users
Rewritten: /api/v2
Backend receives: /api/v2

Pattern 3: Path Transformation

Transform path structure:

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

Example:

Request: /old-api/users
Rewritten: /users
Backend receives: /users

Request Header Modification

Modify request headers before forwarding to the backend.

Nginx Ingress - Request Headers

Nginx Ingress uses annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: header-ingress
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      more_set_headers "X-Custom-Header: value";

Gateway API - RequestHeaderModifier Filter

Gateway API uses native filters:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: header-modify-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-Custom-Header
                value: custom-value
            set:
              - name: X-User-ID
                value: "12345"
            remove:
              - X-Old-Header
      backendRefs:
        - name: my-service
          port: 80

RequestHeaderModifier Operations

Add Headers

Add new headers (doesn't overwrite existing):

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      add:
        - name: X-Forwarded-For
          value: 192.168.1.1
        - name: X-Environment
          value: production

Set Headers

Set header values (overwrites existing):

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      set:
        - name: X-User-ID
          value: "12345"
        - name: Authorization
          value: "Bearer token123"

Remove Headers

Remove headers:

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      remove:
        - X-Sensitive-Header
        - X-Old-Header

Response Header Modification

Modify response headers before sending to the client.

Gateway API - ResponseHeaderModifier Filter

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: response-header-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:
              - name: X-Response-Time
                value: "100ms"
            set:
              - name: Cache-Control
                value: "no-cache"
            remove:
              - X-Internal-Header
      backendRefs:
        - name: my-service
          port: 80

ResponseHeaderModifier Operations

Same operations as RequestHeaderModifier:

add: Add new response headers
set: Set/overwrite response headers
remove: Remove response headers

Redirects

Redirect requests to a different URL.

Nginx Ingress - Redirects

Nginx Ingress uses annotations:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: redirect-ingress
  annotations:
    nginx.ingress.kubernetes.io/permanent-redirect: "https://new.example.com"

Gateway API - RequestRedirect Filter

Gateway API uses native redirect filters:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - old.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            hostname: new.example.com
            statusCode: 301
      backendRefs: []  # No backend needed for redirect

Redirect Options

Permanent Redirect (301)

filters:
  - type: RequestRedirect
    requestRedirect:
      statusCode: 301
      hostname: new.example.com

Temporary Redirect (302)

filters:
  - type: RequestRedirect
    requestRedirect:
      statusCode: 302
      hostname: new.example.com

Path-Specific Redirect

filters:
  - type: RequestRedirect
    requestRedirect:
      path:
        type: ReplaceFullPath
        replaceFullPath: /new-path
      statusCode: 301

HTTP to HTTPS Redirect

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: https-redirect
spec:
  parentRefs:
    - name: http-gateway  # HTTP listener
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestRedirect
          requestRedirect:
            scheme: https
            statusCode: 301
      backendRefs: []

Combining Filters

You can combine multiple filters of different types in a single rule:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: combined-filters-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        # 1. Rewrite URL
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
        # 2. Add request headers
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: X-API-Version
                value: v2
        # 3. Modify response headers
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:
              - name: X-Processed-By
                value: gateway
      backendRefs:
        - name: api-service
          port: 80

Filter execution order:

RequestHeaderModifier
URLRewrite
Request to backend
ResponseHeaderModifier
Response to client

⚠️ NGINX Gateway Fabric Limitation:

NGF supports only one filter of a given type per route rule. If multiple filters of the same type are specified in a single rule, NGF will apply only the first filter and silently ignore subsequent filters of that type.

Exception: Multiple RequestMirror filters are allowed in a single rule.

Example of what won't work in NGF:
filters:
  - type: URLRewrite
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /v1
  - type: URLRewrite  # ❌ This second URLRewrite will be ignored by NGF
    urlRewrite:
      path:
        type: ReplacePrefixMatch
        replacePrefixMatch: /v2
Best Practice: Use only one filter of each type per rule, or split into multiple rules if you need different filter configurations.

Complete Examples

Example 1: API Version Rewrite

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api-rewrite-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /api
      backendRefs:
        - name: v1-service
          port: 80

Example 2: Authentication Header Injection

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: auth-header-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            set:
              - name: Authorization
                value: "Bearer internal-token"
      backendRefs:
        - name: api-service
          port: 80

Example 3: CORS Headers

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: cors-route
spec:
  parentRefs:
    - name: my-gateway
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: ResponseHeaderModifier
          responseHeaderModifier:
            add:
              - name: Access-Control-Allow-Origin
                value: "*"
              - name: Access-Control-Allow-Methods
                value: "GET, POST, PUT, DELETE"
              - name: Access-Control-Allow-Headers
                value: "Content-Type, Authorization"
      backendRefs:
        - name: api-service
          port: 80

Comparison Table

Feature	Nginx Ingress	Gateway API
URL Rewriting	`rewrite-target` annotation	`URLRewrite` filter
Request Headers	Configuration snippets	`RequestHeaderModifier` filter
Response Headers	Limited support	`ResponseHeaderModifier` filter
Redirects	`permanent-redirect` annotation	`RequestRedirect` filter
Multiple Filters	Complex	Native support
Portability	Nginx-specific	Standard across implementations

Best Practices

Filter Order Matters: Understand filter execution order
Use ReplacePrefixMatch: Most common rewrite pattern
Header Security: Be careful with sensitive headers
Redirect Status Codes: Use 301 for permanent, 302 for temporary
Test Thoroughly: URL rewriting can be tricky - test all paths
Document Changes: Document filter behavior for team reference

Common Patterns

Pattern 1: Strip API Prefix

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

Pattern 2: Add Version Header

filters:
  - type: RequestHeaderModifier
    requestHeaderModifier:
      add:
        - name: X-API-Version
          value: v2

Pattern 3: HTTP to HTTPS Redirect

filters:
  - type: RequestRedirect
    requestRedirect:
      scheme: https
      statusCode: 301

Troubleshooting

Rewrite Not Working?

Verify path match type (PathPrefix vs Exact)
Check replacePrefixMatch value
Test with curl to see actual forwarded path
Check Gateway logs for filter processing

Headers Not Appearing?

Verify filter type is correct
Check header name (case-sensitive)
Ensure filter is in the correct rule
Test with curl to inspect headers

Redirect Loop?

Check redirect target doesn't match the original route
Verify status code (301 vs 302)
Ensure redirect filter is in the correct HTTPRoute

Next Steps

Now that you understand request/response modifications, let's learn about policies:

👉 Next: Policies →

httproute-url-rewrite.yaml - URL rewriting
httproute-header-modify.yaml - Header modification
httproute-redirect.yaml - Redirects
ingress-rewrite-equivalent.yaml - Nginx Ingress equivalent

Sources & References

•

Gateway API Official Documentation(Version: v1)

•

NGINX Gateway Fabric Documentation(Version: 2.2.1)

Version Compatibility: This content is based on Gateway API v1 and NGINX Gateway Fabric 2.2.1. Please verify compatibility with your cluster's Gateway API implementation and version.

Request/Response Modifications: Filters and Rewrites

Table of Contents

Request/Response Modifications: Filters and Rewrites

Request/Response Modification Flow

Request Modification

Response Modification

Available Filters

URL Rewrite

Header Modification

Redirect

Request Mirroring

URL Rewriting

Nginx Ingress - Rewrite Target

Gateway API - URLRewrite Filter

URLRewrite Filter Types

1. ReplacePrefixMatch

2. ReplaceFullPath

3. ReplacePathMatch

Common Rewrite Patterns

Pattern 1: Strip Prefix

Pattern 2: Add Prefix

Pattern 3: Path Transformation

Request Header Modification

Nginx Ingress - Request Headers

Gateway API - RequestHeaderModifier Filter

RequestHeaderModifier Operations

Add Headers

Set Headers

Remove Headers

Response Header Modification

Gateway API - ResponseHeaderModifier Filter

ResponseHeaderModifier Operations

Redirects

Nginx Ingress - Redirects

Gateway API - RequestRedirect Filter

Redirect Options

Permanent Redirect (301)

Temporary Redirect (302)

Path-Specific Redirect

HTTP to HTTPS Redirect

Combining Filters

Complete Examples

Example 1: API Version Rewrite

Example 2: Authentication Header Injection

Example 3: CORS Headers

Comparison Table

Best Practices

Common Patterns

Pattern 1: Strip API Prefix

Pattern 2: Add Version Header

Pattern 3: HTTP to HTTPS Redirect

Troubleshooting

Rewrite Not Working?

Headers Not Appearing?

Redirect Loop?

Next Steps

Related Examples

Sources & References