Skip to content
Kong Gateway 2.8 Increases Security and Simplifies API Management.  —Learn More →
|
search
Plugin Hub
header icon

Set Dynamic Upstream Host

This plugin can dynamically construct the upstream hostname and port number based on the key identifier passed in the incoming request. If the same upstream API is deployed in different servers or data centers, then this plugin can form the hostname for the upstream API dynamically to route it to a particular server or data center without making any changes in Kong Route or Service configuration.

Configuration Reference

This plugin is not compatible with DB-less mode.

Enable the plugin on a service

For example, configure this plugin on a service by making the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=set-target-host"  \
    --data "config.upstream_host=example.org" \
    --data "config.string_to_replace_from_host=example" \
    --data "config.header=target"

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <set-target-host-example>
config: 
  upstream_host: example.org
  string_to_replace_from_host: example
  header: target
plugin: set-target-host

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

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

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a service by adding this section to your declarative configuration file:

plugins:
- name: set-target-host
  service: {SERVICE}
  config: 
    upstream_host: example.org
    string_to_replace_from_host: example
    header: target

SERVICE is the id or name of the service that this plugin configuration will target.

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.

For example, configure this plugin globally with:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=set-target-host"  \
    --data "config.upstream_host=example.org" \
    --data "config.string_to_replace_from_host=example" \
    --data "config.header=target"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-set-target-host>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  upstream_host: example.org
  string_to_replace_from_host: example
  header: target
plugin: set-target-host

For example, configure this plugin using the plugins: entry in the declarative configuration file:

plugins:
- name: set-target-host
  config: 
    upstream_host: example.org
    string_to_replace_from_host: example
    header: target

Parameters

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

Form Parameter Description
name
required

Type: string		 The name of the plugin, in this case set-target-host.
service.id

Type: string		 The ID of the Service the plugin targets.
enabled
required

Type: boolean

Default value: true		 Whether this plugin will be applied.
config.upstream_host
required

Type: string

Upstream host with the variable string which has to be replaced by the plugin.

For example, config.upstream_host can be set to example.org.
config.upstream_port
optional

Type: string

Default value: 443

Upstream server port number. Default value is 443 if not provided in plugin configuration.
config.string_to_replace_from_host
required

Type: string

String to replace from the config.upstream_host parameter.

For example, if config.upstream_host is set to example.org and config.string_to_replace_from_host is set to example, then the example string in the upstream host is replaced with the key identifier value from the incoming request dynamically.
config.header
semi-optional

Type: string

Header parameter name used to form the upstream host. Only one header name is supported.

For example, header is set to target, and the incoming request includes the header -H target : httpbin. The value httpbin from the header target is used to form the upstream host. The final upstream hostname formed is httpbin.org, and Kong makes a call to this host.
config.query_arg
semi-optional

Type: string

Query parameter name used to form the upstream host. Only one query parameter name is supported.

For example, query is set to target and the incoming request includes the query /api?target=httpbin. The value httpbin from the query param target is used to form the upstream host. The final upstream hostname formed is httpbin.org, and Kong makes a call to this host.
config.path_index
semi-optional

Type: number

Path parameter index used to form the upstream host. For example, path_index is set to 2, and the incoming request uses the path /api/httpbin. Based on the path index, the second string, httpbin, is extracted from the URI. The final upstream hostname formed is httpbin.org, and Kong makes a call to this host.
config.body_param
semi-optional

Type: string

Request body parameter name used to form the upstream host. Only application/json and application/x-www-form-urlencoded content types are supported. For a JSON message, the field name or JSON Path must be passed.

For example, if the JSON message is {"target": "httpbin"} and config.body_param is set to target, the httpbin value from the target field in the JSON message is used to form the upstream host.

In case of duplicates (target field in JSON), the entire JSON Path needs to be provided. For example, if a form-urlencoded payload contains --data-urlencode 'target=httpbin' and config.body_param is set to target, the httpbin value from the target field in the form body is used to construct the upstream host.

Note: Only one of header, query_arg, path_index, or body_param can be provided at one time, and at least one is required.