/kong-dynamic-upstream

A Kong plugin that sets different upstream URLs based on API and Consumer

Primary LanguageLuaApache License 2.0Apache-2.0

Build Status

kong-dynamic-upstream

A Kong plugin that sets different upstream URLs based on API and Consumer.

The path of the user's request to the API will be appended to the end of the replacement URL. The strip_request_path parameter will be respected.

A request to an API at /foo that is set to strip the request path, http://kong/foo/bar, by a consumer with the dynamic-upstream plugin configured with a replacement_url of https://snafu:4242 will be directed to https://snafu:4242/bar.

The replacement URL must contain:

  • a scheme, eg. HTTPS
  • a hostname, eg. mockbin.com

Optionally you can include:

  • a port, eg. :8080
  • a path, eg. /path

Any existing path in the upstream_url configured for the API will not be replaced by the plugin. For example, an API with an upstream_url of http://www.google.com/foo and a dynamic-upstream plugin with a replacement_url of http://mockbin.com/bin/1234 will route consumers to http://mockbin.com/bin/1234/foo{request_path}.

Some usage examples of valid replacement URLs:

Installation

Clone the repository, navigate to the root folder and run:

make install

Edit your kong.yaml to include the plugin like so:

custom_plugins:
  - dynamic-upstream

Restart Kong.

Development

For a detailed guide on Kong plugin development, check out the official documentation at https://getkong.org/docs/0.8.x/plugin-development/.

This plugin requires Lua 5.1 and the associated version of luarocks. Once you have these installed, to get the development dependencies run the following command:

make dev

Configuration

This plugin can work when attached to All Consumers but really only makes sense when added to a specific Consumer to an API. You can add this plugin to an API and Consumer by making the following request to your Kong server:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=dynamic-upstream" \
    --data "consumer_id=6e62b030-c931-4c72-a012-6be18df81d49" \
    --data "config.replacement_url=http://newupstream:4353/path"

api: The id or name of the API that this plugin configuration will target

Form Parameter Required Description
name required The name of the plugin to use, in this case: dynamic-upstream
consumer_id optional The id of the Consumer to redirect
config.replacement_url required The URL to replace the default upstream specified in the API

Usage Examples

This table details the expected behaviour of the plugin for most of the possible combinations of API and dynamic-upstream plugin configurations.

API upstream_url API request_path strip_request_path Requested Path dynamic-upstream replacement_url Upstream
http://google.com /foo true /foo https://localhost:9999 https://localhost:9999
http://google.com /foo false /foo https://localhost:9999 https://localhost:9999/foo
http://google.com /foo true /foo/bar https://localhost:9999 https://localhost:9999/bar
http://google.com /foo false /foo/bar https://localhost:9999 https://localhost:9999/foo/bar
http://google.com /foo true /foo https://mockbin.com/bin/1234 https://mockbin.com/bin/1234
http://google.com /foo false /foo https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/foo
http://google.com /foo true /foo/bar https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/bar
http://google.com /foo false /foo/bar https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/foo/bar
http://google.com/teapot /foo true /foo https://localhost:9999 https://localhost:9999/teapot
http://google.com/teapot /foo false /foo https://localhost:9999 https://localhost:9999/teapot/foo
http://google.com/teapot /foo true /foo/bar https://localhost:9999 https://localhost:9999/teapot/bar
http://google.com/teapot /foo false /foo/bar https://localhost:9999 https://localhost:9999/teapot/foo/bar
http://google.com/teapot /foo true /foo https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/teapot
http://google.com/teapot /foo false /foo https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/teapot/foo
http://google.com/teapot /foo true /foo/bar https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/teapot/bar
http://google.com/teapot /foo false /foo/bar https://mockbin.com/bin/1234 https://mockbin.com/bin/1234/teapot/foo/bar