Request and Response Rewriting

Ingress provides flexible rewriting capabilities for requests and responses, allowing you to modify headers, paths, query parameters, and more before forwarding to backend services.

Request Rewriting

Request rewriting modifies the request before it's sent to the backend service.

Path Rewriting

Rewrite request paths using regex patterns:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          path:
            rewrites:
              - ^/api/v1/(.*):/api/v2/$1
              - ^/old:/new

The rewrite format is pattern:replacement:

• pattern: Regex pattern to match
• replacement: Replacement string (can use capture groups like $1, $2)

Path Rewrite Examples

Simple Path Rewrite:

request:
  path:
    rewrites:
      - ^/api:/v2/api

Path Rewrite with Capture Groups:

request:
  path:
    rewrites:
      - ^/api/v1/(.*):/api/v2/$1

This rewrites /api/v1/users to /api/v2/users.

Multiple Path Rewrites:

request:
  path:
    rewrites:
      - ^/ip3/(.*):/$1
      - ^/ip2:/ip

Rewrites are applied in order. The first matching rewrite is used.

Host Header Rewriting

backend.service.mode (and legacy backend.mode) are documented in the Configuration reference (rules · backend fields).

The upstream Host header is controlled in two layers:

1. service.request.host.rewrite: Optional. When set to true or false, it always wins over service.mode / backend.mode.
2. service.mode (when rewrite is omitted; falls back to backend.mode if service.mode is empty):
   • internal (default): keep the client Host header.
   • external: set Host to the upstream service host (service name, plus port when non-default for the protocol). Use for third-party or off-cluster origins that validate Host.

Global fallback: when no rule matches, if rewrite is omitted, Host is still aligned to the fallback upstream (same practical need as many external rules). Set fallback.service.request.host.rewrite: false only if you must preserve the client Host.

Explicit rewrite example:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          host:
            rewrite: true

Preferred when mirroring a public HTTPS origin:

rules:
  - host: mirror.example.com
    backend:
      service:
        mode: external
        protocol: https
        name: upstream.example.org
        # port optional for https — defaults to 443

A larger runnable sample with internal upstreams, service.mode: external HTTPS proxies, and handler paths is examples/advanced/service-mode-external-mixed.yaml.

When rewrite: true, the Host header matches what service.Host() uses for the upstream connection (including port formatting).

Header Modification

Add or modify request headers:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          headers:
            X-Forwarded-Proto: https
            X-Custom-Header: value
            X-User-ID: "12345"

Headers are added or overwritten. Common use cases:

• Set X-Forwarded-Proto for HTTPS detection
• Add authentication headers
• Pass user information
• Set custom headers for backend services

Query Parameter Modification

Add or modify query parameters:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          query:
            api_key: secret-key
            version: v2

Query parameters are added to the request. If a parameter already exists, it may be overwritten.

Request Delay

Add a delay before forwarding the request:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          delay: 100  # Delay in milliseconds

Useful for:

• Rate limiting simulation
• Testing timeout behavior
• Throttling requests

Request Timeout

Set a timeout for backend requests:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          timeout: 30  # Timeout in seconds

If the backend doesn't respond within the timeout, the request fails.

Response Rewriting

Response rewriting modifies the response before sending it to the client.

Response Header Modification

Modify response headers:

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        response:
          headers:
            X-Custom-Header: value
            Cache-Control: no-cache

Common use cases:

• Add security headers
• Modify caching headers
• Add custom headers for clients

Complete Rewriting Example

rules:
  - host: example.com
    backend:
      service:
        name: backend-service
        port: 8080
        request:
          host:
            rewrite: true
          path:
            rewrites:
              - ^/api/v1/(.*):/api/v2/$1
          headers:
            X-Forwarded-Proto: https
            X-Custom-Header: value
          query:
            version: v2
          delay: 0
          timeout: 30
        response:
          headers:
            X-Response-Header: value

Path Rewriting with Regex

Capture Groups

Use capture groups in path rewrites:

request:
  path:
    rewrites:
      - ^/api/v1/([^/]+)/(.*):/api/v2/$1/$2

This captures two groups and reorders them.

Complex Path Rewrites

rules:
  - host: httpbin.example.work
    backend:
      service:
        mode: external
        protocol: https
        name: httpbin.zcorky.com
        request:
          path:
            rewrites:
              - ^/ip3/(.*):/$1
              - ^/ip2:/ip
    paths:
      - path: /httpbin.org
        backend:
          service:
            mode: external
            protocol: https
            name: httpbin.org
            request:
              path:
                rewrites:
                  - ^/httpbin.org/(.*):/$1

Best Practices

1. Test Rewrite Patterns: Verify regex patterns match as expected
2. Order Matters: Place more specific rewrites before general ones
3. Use Capture Groups: Leverage regex capture groups for flexible rewrites
4. Preserve Important Headers: Be careful not to overwrite critical headers
5. Document Rewrites: Document complex rewrite rules for maintainability
6. Monitor Impact: Monitor how rewrites affect backend services

Common Use Cases

API Version Migration

request:
  path:
    rewrites:
      - ^/api/v1/(.*):/api/v2/$1

Path Normalization

request:
  path:
    rewrites:
      - ^/old-path/(.*):/new-path/$1

Adding Authentication Headers

request:
  headers:
    Authorization: Bearer token-here

Setting Protocol Information

request:
  headers:
    X-Forwarded-Proto: https
    X-Forwarded-For: $remote_addr

Troubleshooting

Rewrite Not Working

• Verify the regex pattern matches the path
• Check the rewrite order (first match wins)
• Ensure the rewrite syntax is correct (pattern:replacement)
• Test the regex pattern separately

Headers Not Set

• Verify header names are correct
• Check for typos in header values
• Ensure headers are in the correct section (request vs response)

Path Rewrite Issues

• Test regex patterns with a regex tester
• Verify capture group references ($1, $2, etc.)
• Check for escaping issues in special characters