Community Plugin: This plugin is developed, tested, and maintained by a third-party contributor.
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 compatible with DB-less mode.
Example plugin configuration
Enable on a service
Enable globally
The following examples provide some typical configurations for enabling
the set-target-host
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=set-target-host" \
--data "config.upstream_host=example.org" \
--data "config.string_to_replace_from_host=example" \
--data "config.header=target"
Replace SERVICE_NAME|SERVICE_ID
with 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_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: set-target-host-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with 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
.
Add this section to your declarative configuration file:
plugins:
- name: set-target-host
service: SERVICE_NAME|SERVICE_ID
config:
upstream_host: example.org
string_to_replace_from_host: example
header: target
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
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.
The following examples provide some typical configurations for enabling
the set-target-host
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Make the following request:
curl -X POST http://localhost: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
Add a 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.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
enabled
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.