Skip to navigation

Transformer plugin

The Transformer plugin changes request headers, query parameters, cookies, and JSON body fields before the gateway forwards the request. It can also change response headers, status, cookies, and JSON body fields. Rules run in the order you list them. Transformer is a Preview plugin.

On an Enterprise data plane, Transformer needs the OPA policy sidecar, which the Helm chart turns on with opa.enabled. It’s off by default, and Transformer has no in-process fallback. Without the sidecar, the plugin fails according to its on_error setting, which defaults to fail_closed, so the request fails. The data plane must allow Preview plugins. For more information, see Helm values.

Where it runs

ProtocolsRequest rules: all. Response rules: HTTP routes only, for responses that aren’t streamed and are at most 1 MiB.
Scope kindsglobal, service, route. The API also accepts consumer, but the console doesn’t offer it.
PhaseRequest and response

Only the instance at the narrowest scope runs.

Configuration

rules
array of objects

The changes to make, in order. A rule whose target starts with response. runs on the response.

rules[].op
stringRequired

The operation. See the list after this table.

rules[].target
stringRequired

What to change: request.method, request.path, request.header.<name>, request.query.<name>, request.body.<path>, request.cookie.<name>, response.header.<name>, response.status, response.body.<path>, or response.cookie.<name>. headers and cookies work as plural forms, for example request.headers.<name>. request.method takes only set, template, copy, move, and rename. request.path takes only set and template, and each value substituted into a path template is escaped as one path segment.

rules[].value
string

The value for set, add, default, and template. A value written to a body field is stored as JSON when it parses as JSON, otherwise as a string.

rules[].from
string

The source for copy, move, rename, and hash, for example identity.consumer, request.header.<name>, or request.body.<path>.

rules[].cookie
object

For response cookie targets only: path, domain, max_age, secure, http_only, and same_site (lax, strict, or none).

The operations do the following:

  • set replaces the target with value.
  • add adds value beside existing header or query values.
  • default sets value only if the target is absent.
  • remove deletes the target. add and remove aren’t valid on response.status, and default on a response cookie always sets the value.
  • copy sets the target to the value of from.
  • move and rename copy, then delete the source when it’s a header, query parameter, body field, or request cookie.
  • template sets the target to value with every {{ reference }} replaced, for example {{ identity.consumer }}.
  • hash sets the target to the lowercase hexadecimal SHA-256 of from, or of the target itself when from is omitted.

The Authorization header, and headers that the gateway fills with credentials, can’t be read as sources.

Example

{
"name": "add-caller-header",
"plugin_id": "transformer",
"scope": { "kind": "route", "name": "orders-api" },
"config": {
"rules": [
{ "op": "set", "target": "request.header.X-Api-Key", "value": "prod" },
{ "op": "copy", "target": "request.header.X-Caller", "from": "identity.consumer" },
{ "op": "remove", "target": "response.header.Server" }
]
}
}