Transformations

Reference for request and response transformation policies — header modification, URL rewriting, redirects, mirroring, and body transformations.

Transformation policies allow you to modify requests and responses as they pass through Agentgateway. Transformations are applied at the route level under binds[].listeners[].routes[].policies.

Agentgateway supports the following transformation types:

• requestHeaderModifier — add, set, or remove request headers
• responseHeaderModifier — add, set, or remove response headers
• requestRedirect — respond directly with an HTTP redirect
• urlRewrite — modify the URL path or authority before forwarding
• requestMirror — mirror requests to a secondary backend
• directResponse — respond directly with a static body without forwarding
• transformations — modify request and response bodies and headers

requestHeaderModifier

Modify headers on the inbound request before it is forwarded to the backend.

policies:
  requestHeaderModifier:
    add:
      x-request-source: agentgateway
    set:
      x-forwarded-host: gateway.example.com
    remove:
    - x-internal-debug

requestHeaderModifier · object

Headers to be modified on the inbound request.

Show requestHeaderModifier fields

requestHeaderModifier.add · object

Key-value pairs of headers to add to the request. If the header already exists, a new header with the same name is appended.

requestHeaderModifier:
  add:
    x-custom-header: my-value

requestHeaderModifier.set · object

Key-value pairs of headers to set on the request. If the header already exists, its value is overwritten.

requestHeaderModifier:
  set:
    x-forwarded-for: 10.0.0.1

requestHeaderModifier.remove · string[]

List of header names to remove from the request.

requestHeaderModifier:
  remove:
  - x-debug-token
  - x-internal-id

responseHeaderModifier

Modify headers on the response from the backend before it is returned to the client.

policies:
  responseHeaderModifier:
    add:
      x-served-by: agentgateway
    remove:
    - server
    - x-powered-by

responseHeaderModifier · object

Headers to be modified on the outbound response.

Show responseHeaderModifier fields

responseHeaderModifier.add · object

Key-value pairs of headers to add to the response.

responseHeaderModifier.set · object

Key-value pairs of headers to set on the response, overwriting existing values.

responseHeaderModifier.remove · string[]

List of header names to remove from the response.

responseHeaderModifier:
  remove:
  - server
  - x-powered-by

requestRedirect

Respond directly to the client with an HTTP redirect without forwarding the request to a backend.

policies:
  requestRedirect:
    scheme: https
    authority:
      host: api.example.com
    status: 301

requestRedirect · object

Directly respond to the request with a redirect.

Show requestRedirect fields

requestRedirect.scheme · string

The redirect scheme. Typically http or https.

requestRedirect:
  scheme: https

requestRedirect.authority · object

The redirect authority (host and/or port). One of full, host, or port.

Show authority options

requestRedirect.authority.full · string

Full authority string including host and port (e.g. api.example.com:443).

requestRedirect.authority.host · string

Host portion only.

requestRedirect.authority.port · integer

Port portion only.

requestRedirect.path · object

The redirect path. One of full or prefix.

Show path options

requestRedirect.path.full · string

Replace the entire path with this value.

requestRedirect.path.prefix · string

Replace the matched path prefix with this value.

requestRedirect.status · integer

HTTP redirect status code. Common values: 301 (permanent), 302 (temporary), 307, 308.

requestRedirect:
  status: 301

urlRewrite

Modify the URL path or authority before forwarding the request to the backend. Unlike requestRedirect, the client does not see the rewrite — it receives the backend’s response as if the original URL was used.

policies:
  urlRewrite:
    authority:
      host: internal-backend.example.com
    path:
      prefix: /v2

urlRewrite · object

Modify the URL path or authority before forwarding.

Show urlRewrite fields

urlRewrite.authority · object

Override the request authority. One of full, host, or port.

Show authority options

urlRewrite.authority.full · string

Full authority string.

urlRewrite.authority.host · string

Host portion only.

urlRewrite.authority.port · integer

Port portion only.

urlRewrite.path · object

Override the request path. One of full or prefix.

Show path options

urlRewrite.path.full · string

Replace the entire path.

urlRewrite.path.prefix · string

Replace the matched path prefix.

requestMirror

Mirror (shadow) incoming requests to a secondary backend in addition to the primary backend. The client only receives the response from the primary backend. The mirror backend’s response is discarded.

policies:
  requestMirror:
    backend: shadow-backend
    percentage: 10

requestMirror · object

Mirror incoming requests to another destination.

Show requestMirror fields

requestMirror.backend · object

The mirror destination. One of service, host, or backend.

Show backend options

requestMirror.backend.service · object

Reference to a named service.

Show service fields

service.name.namespace · string

Namespace of the service.

service.name.hostname · string

Hostname of the service.

service.port · integer

Port of the service.

requestMirror.backend.host · string

Hostname or IP address of the mirror backend.

requestMirror.backend.backend · string

Name of a backend defined in the top-level backends list.

requestMirror.percentage · integer

Percentage of requests to mirror (0–100). When omitted, all matching requests are mirrored.

requestMirror:
  percentage: 10

directResponse

Respond directly to the client with a static response body and status code, without forwarding to any backend.

policies:
  directResponse:
    status: 200
    body: '{"status": "ok"}'

directResponse · object

Directly respond to the request with a static response.

Show directResponse fields

directResponse.status · integer · required

HTTP status code for the response.

directResponse:
  status: 200

directResponse.body · string

Response body string.

directResponse:
  status: 200
  body: '{"message": "Service unavailable"}'

transformations

Modify request and response bodies, headers, and metadata using structured transformation rules.

policies:
  transformations:
    request:
      add:
        x-request-id: some-value
      set:
        content-type: application/json
      remove:
      - x-debug
    response:
      add:
        x-proxy: agentgateway
      remove:
      - server

transformations · object

Modify requests and responses sent to and from the backend.

Show transformations fields

transformations.request · object

Transformations applied to the inbound request.

Show request transformation fields

transformations.request.add · object

Headers to add to the request.

transformations.request.set · object

Headers to set on the request (overwriting existing values).

transformations.request.remove · string[]

Headers to remove from the request.

transformations.request.body · object

Modifications to apply to the request body.

transformations.request.metadata · object

Metadata to attach to the request.

transformations.response · object

Transformations applied to the response from the backend.

Show response transformation fields

transformations.response.add · object

Headers to add to the response.

transformations.response.set · object

Headers to set on the response.

transformations.response.remove · string[]

Headers to remove from the response.

transformations.response.body · object

Modifications to apply to the response body.

transformations.response.metadata · object

Metadata to attach to the response.

Combined example

binds:
- port: 3000
  listeners:
  - routes:
    - matches:
      - path:
          pathPrefix: /api/
      policies:
        requestHeaderModifier:
          add:
            x-request-source: agentgateway
          remove:
          - x-internal-token
        responseHeaderModifier:
          remove:
          - server
          - x-powered-by
        urlRewrite:
          path:
            prefix: /v2
        transformations:
          request:
            set:
              content-type: application/json
          response:
            add:
              x-proxy: agentgateway
      backends:
      - host: http://api-backend:8080

requestHeaderModifier and responseHeaderModifier operate on individual HTTP headers, while transformations provides a broader object with support for request/response body modifications. Both can be used together on the same route.