Route By Header

You are browsing unreleased documentation.

Looking for the plugin's configuration parameters? You can find them in the Route By Header configuration reference doc.

Kong Gateway plugin to route requests based on request headers.

Rules

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 serviceA, which routes all the requests to upstream default.domain.com.

Add an upstream object and a target:

curl -i -X POST http://localhost:8001/upstreams -d name=default.domain.com

Response:

HTTP/1.1 201 Created
...
{created_at":1534537731231, .. "slots":10000}

curl -i -X POST http://localhost:8001/upstreams/default.domain.com/targets --data target="default.host.com:9000"

Response:

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://localhost:8001/services --data protocol=http --data host=default.domain.com --data name=serviceA

Response:

HTTP/1.1 201 Created
...
{"host":"default.domain.com", .. ,"write_timeout":60000}

curl -i -X POST http://localhost:8001/routes  --data "paths[]=/" --data service.id=6e7f5274-62da-469e-bdd5-03c4a212c15b

Response:

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

Response:

HTTP/1.1 201 Created
...
{"created_at":1534541064946, .. ,"slots":10000}

curl -i -X POST http://localhost:8001/upstreams/east.domain.com/targets --data target="east.host.com:9001"

Response:

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

Response:

HTTP/1.1 201 Created
...
{"created_at":1534541385227, .. ,"slots":10000}

curl -i -X POST http://localhost:8001/upstreams/west.domain.com/targets --data target="west.host.com:9002"

Response:

HTTP/1.1 201 Created
...
{"created_at":1534541405038, .. ,"id":"96cb469f-280f-4b0a-bd3d-1a0599b82585"}

Enable plugin on service serviceA:

curl -i -X POST http://localhost:8001/services/serviceA/plugins \
  -H 'Content-Type: application/json' \
  --data '{"name": "route-by-header", "config": {"rules":[{"condition": {"location":"us-east"}, "upstream_name": "east.domain.com"}, {"condition": {"location":"us-west"}, "upstream_name": "west.domain.com"}]}}'

Response:

HTTP/1.1 201 Created
...
{"created_at":1534540916000,"config":{"rules":{"":"{\"condition\": {\"location\":\"us-east\"}, \"upstream_name\": \"east.domain.com\"}, {\"condition\": {\"location\":\"us-west\"}, \"upstream_name\": \"west.domain.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://localhost: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.domain.com"}, {"condition": {"location":"us-west"}, "upstream_name": "west.domain.com"},  {"condition": {"location":"us-south", "region": "US"}, "upstream_name": "south.domain.com"}]}}'

Response:

HTTP/1.1 200 OK
...
{"created_at":1534540916000,"config":{"rules":{"":"{\"condition\": {\"location\":\"us-east\"}, \"upstream_name\": \"east.domain.com\"}, {\"condition\": {\"location\":\"us-west\"}, \"upstream_name\": \"west.domain.com\"}, {\"condition\": {\"location\":\"us-south\", \"region\": \"us\"}, \"upstream_name\": \"south.domain.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.