Kong Enterprise only: This plugin is only available with a Kong Enterprise subscription.
Please inquire about Kong Enterprise by contacting us - or start a free trial today.

Kong Enterprise plugin to route requests based on request headers.


Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • Service: the Kong entity representing an external upstream API or microservice.
  • Route: the Kong entity representing a way to map downstream requests to upstream services.
  • Consumer: the Kong entity representing a developer or machine using the API. When using Kong, a Consumer only communicates with Kong which proxies every call to the said upstream API.
  • Credential: a unique string associated with a Consumer, also referred to as an API key.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
  • API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=route-by-header" 

  • service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=route-by-header" 

  • route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on a Consumer

You can use the http://localhost:8001/plugins endpoint to enable this plugin on specific Consumers:

$ curl -X POST http://kong:8001/plugins \
    --data "name=route-by-header" \
    --data "consumer_id={consumer_id}" 

Where consumer_id is the id of the Consumer we want to associate with this plugin.

You can combine consumer_id and service_id

in the same request, to furthermore narrow the scope of the plugin.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=route-by-header" 

  • api: either id or name of the API that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

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

form parameterdefaultdescription
nameThe name of the plugin to use, in this case route-by-header
service_idThe id of the Service which this plugin will target.
route_idThe id of the Route which this plugin will target.
enabledtrueWhether this plugin will be applied.
consumer_idThe id of the Consumer which this plugin will target.
api_idThe id of the API which this plugin will target. Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.
config.rules
optional

{}

List of rules

Rules

parameter description
condition List of headers name and value pairs
upstream_name Target hostname where traffic will be routed in case of condition match

Note: if more than one pair of header name and value is provided, the plugin looks for all of these in the request - that is, requests must contain all of the specified headers with the specified values for a match to occur.

Usage

The plugin will route a request to a new upstream target if it matches one of the configured rules. Each rule consists of a condition object and an upstream_name object. For each request coming into Kong, the plugin will try to find a rule where all the headers defined in the condition field have the same value as in the incoming request. The first such match dictates the upstream to which the request is forwarded to.

Example

Let’s run through an example scenario to demonstrate the plugin. Let’s say we have a Kong service searviceA, which routes all the requests to upstream default.domain.com.

Add an upstream object and a target:

$ curl -i -X POST http://kong:8001/upstreams -d name=default.domain.com
HTTP/1.1 201 Created
...
{created_at":1534537731231, .. "slots":10000}
$ curl -i -X POST http://kong:8001/upstreams/default.domain.com/targets --data target="default.host.com:9000"
HTTP/1.1 201 Created
...
{"created_at":1534538010468, .. ,"id":"ffd8815b-fd6c-4e0e-aa67-06e9cda39c3b"}

Now we will add a service and a route object, using the upstream default.domain.com we just created:

$ curl -i -X POST http://kong:8001/services --data protocol=http --data host=default.domain.com --data name=serviceA
HTTP/1.1 201 Created
...
{"host":"default.domain.com", .. ,"write_timeout":60000}
$ curl -i -X POST http://kong:8001/routes  --data "paths[]=/" --data service.id=6e7f5274-62da-469e-bdd5-03c4a212c15b
HTTP/1.1 201 Created
...
{"created_at":1534538701, .. ,"id":"12ceb66b-51ed-488a-9de0-112270e6f370"}

Now any request made to service serviceA will be routed to the upstream default.domain.com. But let’s say we want to route some of these requests to different upstreams, dynamically, based on some information provided through request headers. This is the exact situation where this plugin can be helpful.

Let’s apply this plugin on serviceA to route all requests with a header Location set to us-east to upstream east.domain.com and requests with a header Location set to us-west to upstream west.domain.com.

Add the two upstreams and corresponding targets:

$ curl -i -X POST http://localhost:8001/upstreams -d name=east.domain.com
HTTP/1.1 201 Created
...
{"created_at":1534541064946, .. ,"slots":10000}
$ curl -i -X POST http://kong:8001/upstreams/east.domain.com/targets --data target="east.host.com:9001"
HTTP/1.1 201 Created
...
{"created_at":1534541248416, .. ,"id":"3164a588-09d7-4a72-895f-fa19535e3682"}
$ curl -i -X POST http://localhost:8001/upstreams -d name=west.domain.com
HTTP/1.1 201 Created
...
{"created_at":1534541385227, .. ,"slots":10000}
$ curl -i -X POST http://kong:8001/upstreams/west.domain.com/targets --data target="west.host.com:9002"
HTTP/1.1 201 Created
...
{"created_at":1534541405038, .. ,"id":"96cb469f-280f-4b0a-bd3d-1a0599b82585"}

Enable plugin on service serviceA:

$ curl -i -X POST http://kong:8001/services/serviceA/plugins -H 'Content-Type: application/json' --data '{"name": "route-by-header", "config": {"rules":[{"condition": {"location":"us-east"}, "upstream_name": "east.doamin.com"}, {"condition": {"location":"us-west"}, "upstream_name": "west.doamin.com"}]}}'
HTTP/1.1 201 Created
...
{"created_at":1534540916000,"config":{"rules":{"":"{\"condition\": {\"location\":\"us-east\"}, \"upstream_name\": \"east.doamin.com\"}, {\"condition\": {\"location\":\"us-west\"}, \"upstream_name\": \"west.doamin.com\"}"}},"id":"0df16085-76b2-4a50-ac30-c8a1eade389a","enabled":true,"service_id":"6e7f5274-62da-469e-bdd5-03c4a212c15b","name":"route-by-header"}

Now, any request with header Location set to us-east will route to upstream east.domain.com and requests with header Location set to us-west will route to upstream west.domain.com.

You can also provide multiple headers as matching condition. The plugin does an AND on the provided headers in the condition field of each rule.

Let’s patch above plugin to add one more rule with multiple headers:

$ curl -i -X PATCH http://kong:8001/plugins/0df16085-76b2-4a50-ac30-c8a1eade389a -H 'Content-Type: application/json' --data '{"name": "route-by-header", "config": {"rules":[{"condition": {"location":"us-east"}, "upstream_name": "east.doamin.com"}, {"condition": {"location":"us-west"}, "upstream_name": "west.doamin.com"},  {"condition": {"location":"us-south", "region": "US"}, "upstream_name": "south.doamin.com"}]}}'
HTTP/1.1 200 OK
...
{"created_at":1534540916000,"config":{"rules":{"":"{\"condition\": {\"location\":\"us-east\"}, \"upstream_name\": \"east.doamin.com\"}, {\"condition\": {\"location\":\"us-west\"}, \"upstream_name\": \"west.doamin.com\"}, {\"condition\": {\"location\":\"us-south\", \"region\": \"us\"}, \"upstream_name\": \"south.doamin.com\"}"}},"id":"0df16085-76b2-4a50-ac30-c8a1eade389a","enabled":true,"service_id":"6e7f5274-62da-469e-bdd5-03c4a212c15b","name":"route-by-header"}

Now we have an additional rule which routes any request with header Location set to us-south and Region set to US route to upstream south.domain.com.