Request Transformer Advanced

The Request Transformer plugin for Kong Gateway builds on the Kong version of this plugin with enhanced capabilities to match portions of incoming requests using regular expressions, save those matched strings into variables, and substitute those strings into transformed requests via flexible templates.

Configuration Reference

Enable the plugin on a service

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=request-transformer-advanced" 

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-transformer-advanced-example>
config:
  <optional_parameter>: <value>
plugin: request-transformer-advanced

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <request-transformer-advanced-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    app: {SERVICE}

plugins:
- name: request-transformer-advanced
  service: {SERVICE}
  config:
    <optional_parameter>: <value>

Enable the plugin on a route

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=request-transformer-advanced" 

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-transformer-advanced-example>
config:
  <optional_parameter>: <value>
plugin: request-transformer-advanced

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <request-transformer-advanced-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

plugins:
- name: request-transformer-advanced
  route: <route>
  config:
    <optional_parameter>: <value>

Enabling the plugin on a consumer

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=request-transformer-advanced" 

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <request-transformer-advanced-example>
config:
  <optional_parameter>: <value>
plugin: request-transformer-advanced

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <request-transformer-advanced-example>
    kubernetes.io/ingress.class: kong

plugins:
- name: request-transformer-advanced
  consumer: {CONSUMER}
  config:
    <optional_parameter>: <value>

Enable the plugin globally

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=request-transformer-advanced" 

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-request-transformer-advanced>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config:
  <optional_parameter>: <value>
plugin: request-transformer-advanced

plugins:
- name: request-transformer-advanced
  config:
    <optional_parameter>: <value>

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

Notes:

• If the value contains a , then the comma separated format cannot be used. The array notation must be used instead.
• The X-Forwarded-* fields are non-standard header fields written by Nginx to inform the upstream about client details and can’t be overwritten by this plugin. If you need to overwrite these header fields, see the post-function plugin in Serverless Functions.

Template as Value

User can use any of the the current request headers, query params, and captured URI groups as template to populate above supported config fields.

To escape a template, wrap it inside quotes and pass inside another template.
Ex. $(‘$(some_needs_to_escaped)’)

Note: The plugin creates a non-mutable table of request headers, querystrings, and captured URIs before transformation. So any update or removal of params used in template does not affect the rendered value of template.

Advanced templates

The content of the placeholder $(...) is evaluated as a Lua expression, so logical operators may be used. For example:

Header-Name:$(uri_captures["user-id"] or query_params["user"] or "unknown")

This will first look for the path parameter (uri_captures); if not found, it will return the query parameter; or if that also doesn’t exist, it returns the default value ‘“unknown”’.

Constant parts can be specified as part of the template outside the dynamic placeholders. For example, creating a basic-auth header from a query parameter called auth that only contains the base64-encoded part:

Authorization:Basic $(query_params["auth"])

Lambdas are also supported if wrapped as an expression like this:

$((function() ... implementation here ... end)())

A complete lambda example for pefixing a header value with “Basic “ if not already there:

Authorization:$((function()
    local value = headers.Authorization
    if not value then
      return
    end
    if value:sub(1, 6) == "Basic " then
      return value            -- was already properly formed
    end
    return "Basic " .. value  -- added proper prefix
  end)())

NOTE: Especially in multi-line templates like the example above, make sure not to add any trailing white-space or new-lines. Since these would be outside the placeholders, they would be considered part of the template, and hence would be appended to the generated value.

The environment is sandboxed, meaning that Lambda’s will not have access to any library functions, except for the string methods (like sub() in the example above).

Examples Using Template as Value

Add a Service named test with uris configured with a named capture group user_id:

$ curl -X POST http://localhost:8001/services \
    --data 'name=test' \
    --data 'upstream_url=http://mockbin.com' \
    --data-urlencode 'uris=/requests/user/(?<user_id>\w+)' \
    --data "strip_uri=false"

Enable the ‘request-transformer-advanced’ plugin to add a new header x-consumer-id and its value is being set with the value sent with header x-user-id or with the default value alice is header is missing.

$ curl -X POST http://localhost:8001/services/test/plugins \
    --data "name=request-transformer-advanced" \
    --data-urlencode "config.add.headers=x-consumer-id:\$(headers['x-user-id'] or 'alice')" \
    --data "config.remove.headers=x-user-id"

Now send a request without setting header x-user-id

$ curl -i -X GET localhost:8000/requests/user/foo

Plugin will add a new header x-consumer-id with value alice before proxying request upstream. Now try sending request with header x-user-id set

$ curl -i -X GET localhost:8000/requests/user/foo \
  -H "X-User-Id:bob"

This time plugin will add a new header x-consumer-id with value sent along with header x-user-id, i.e.bob

Order of Execution

This plugin performs the response transformation in the following order:

remove –> replace –> add –> append

Configuration Examples

Add multiple headers by passing each header:value pair separately:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --data "name=request-transformer-advanced" \
  --data "config.add.headers[1]=h1:v1" \
  --data "config.add.headers[2]=h2:v1"

Add multiple headers by passing comma separated header:value pair:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --data "name=request-transformer-advanced" \
  --data "config.add.headers=h1:v1,h2:v2"

Add multiple headers passing config as JSON body:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --header 'content-type: application/json' \
  --data '{"name": "request-transformer-advanced", "config": {"add": {"headers": ["h1:v2", "h2:v1"]}}}'

Add a querystring and a header:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --data "name=request-transformer-advanced" \
  --data "config.add.querystring=q1:v2,q2=v1" \
  --data "config.add.headers=h1:v1"

Append multiple headers and remove a body parameter:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --data "name=request-transformer-advanced" \
  --data "config.add.headers=h1:v2,h2:v1" \
  --data "config.remove.body=p1" \

Add multiple headers and querystring parameters if not already set:

$ curl -X POST http://localhost:8001/services/mockbin/plugins \
  --data "name=request-transformer-advanced" \
  --data "config.add.headers=h1:v1,h2:v1" \
  --data "config.add.querystring=q1:v2,q2:v1" \