The Forward Proxy plugin allows Kong to connect to intermediary transparent
HTTP proxies, instead of directly to the upstream_url, when forwarding requests
upstream. This is useful in environments where Kong sits in an organization’s
internal network, the upstream API is available via the public internet, and
the organization proxies all outbound traffic through a forward proxy server.
Please note that this plugin can’t be used with an upstream. As a workaround for load balancing,
configure the host field in service to a domain name so that you can
use a DNS-based load balancing technique.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway
declaratively.
Therefore, the Admin API is mostly read-only. The only tasks it can perform are all
related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Example plugin configuration
Enable on a service
Enable on a route
Enable on a consumer
Enable globally
The following examples provide some typical configurations for enabling
the forward-proxy
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=forward-proxy" \
--data "config.http_proxy_host=example.com" \
--data "config.http_proxy_port=80" \
--data "config.proxy_scheme=http" \
--data "config.auth_username=example_user" \
--data "config.auth_password=example_pass" \
--data "config.https_verify=false" \
--data "config.x_headers=transparent"
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: forward-proxy-example
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
plugin: forward-proxy
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: forward-proxy-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: forward-proxy
service: SERVICE_NAME|SERVICE_ID
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- In the Plugins section, click Add Plugin.
- Find and select the Forward Proxy Advanced plugin.
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the Forward Proxy Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
- Click Create.
The following examples provide some typical configurations for enabling
the forward-proxy
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Konnect Cloud
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=forward-proxy" \
--data "config.http_proxy_host=example.com" \
--data "config.http_proxy_port=80" \
--data "config.proxy_scheme=http" \
--data "config.auth_username=example_user" \
--data "config.auth_password=example_pass" \
--data "config.https_verify=false" \
--data "config.x_headers=transparent"
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: forward-proxy-example
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
plugin: forward-proxy
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: forward-proxy-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route 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: forward-proxy
route: ROUTE_NAME
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Konnect UI.
From the
Service Hub, select a service version, then set up the plugin:
- Select a route.
- In the Plugins section, click Add Plugin.
- Find and select the Forward Proxy Advanced plugin.
- Click Create.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the Forward Proxy Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
- Click Create.
The following examples provide some typical configurations for enabling
the forward-proxy
plugin on a
consumer.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/consumers/CONSUMER_NAME|CONSUMER_ID/plugins \
--data "name=forward-proxy" \
--data "config.http_proxy_host=example.com" \
--data "config.http_proxy_port=80" \
--data "config.proxy_scheme=http" \
--data "config.auth_username=example_user" \
--data "config.auth_password=example_pass" \
--data "config.https_verify=false" \
--data "config.x_headers=transparent"
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can combine consumer.id
, service.id
, or route.id
in the same request, to further narrow the scope of the plugin.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: forward-proxy-example
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
plugin: forward-proxy
Then, apply it to a consumer by
annotating the KongConsumer resource as follows:
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
name: CONSUMER_NAME|CONSUMER_ID
annotations:
konghq.com/plugins: forward-proxy-example
kubernetes.io/ingress.class: kong
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer 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: forward-proxy
consumer: CONSUMER_NAME|CONSUMER_ID
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Consumers section, click View for the consumer row.
- Select the Plugins tab, then click Add Plugin.
- Find and select the Forward Proxy Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, select Scoped.
- Add the consumer ID if it is not already prefilled.
- Click Create.
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 forward-proxy
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=forward-proxy" \
--data "config.http_proxy_host=example.com" \
--data "config.http_proxy_port=80" \
--data "config.proxy_scheme=http" \
--data "config.auth_username=example_user" \
--data "config.auth_password=example_pass" \
--data "config.https_verify=false" \
--data "config.x_headers=transparent"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-forward-proxy>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
plugin: forward-proxy
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: forward-proxy
config:
http_proxy_host: example.com
http_proxy_port: 80
proxy_scheme: http
auth_username: example_user
auth_password: example_pass
https_verify: false
x_headers: transparent
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the Forward Proxy Advanced plugin.
Note: If the plugin is greyed out, then it is not available
for your product tier. See Kong Gateway tiers.
- If the option is available, set the plugin scope to Global.
- Click Create.
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 forward-proxy . |
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 . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
consumer.name or consumer.id
Type: string |
The name or ID of the consumer the plugin targets.
Set one of these parameters if adding the plugin to a consumer through the top-level /plugins endpoint.
Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins . |
enabled
Type: boolean
Default value: true |
Whether this plugin will be applied. |
config.http_proxy_host
semi-optional
Type: string
|
The HTTP hostname or IP address of the forward proxy to which to connect.
Required if http_proxy_port is set.
At least one of http_proxy_host or https_proxy_host must be specified.
If http_proxy_host isn’t set, the plugin falls back to the value
configured in https_proxy_host .
|
config.http_proxy_port
semi-optional
Type: string
|
The TCP port of the HTTP forward proxy to which to connect.
Required if http_proxy_host is set.
At least one of http_proxy_port or https_proxy_port must be specified.
If http_proxy_port isn’t set, the plugin falls back to the value
configured in https_proxy_port .
|
config.https_proxy_host
semi-optional
Type: string
|
The HTTPS hostname or IP address of the forward proxy to which to connect.
Required if https_proxy_port is set.
At least one of http_proxy_host or https_proxy_host must be specified.
If https_proxy_host isn’t set, the plugin falls back to the value
configured in http_proxy_host .
|
config.https_proxy_port
semi-optional
Type: string
|
The TCP port of the HTTPS forward proxy to which to connect.
Required if https_proxy_host is set.
At least one of http_proxy_port or https_proxy_port must be specified.
If https_proxy_port isn’t set, the plugin falls back to the value
configured in http_proxy_port .
|
config.proxy_scheme
optional
Type: string
Default value: http
|
The proxy scheme to use when connecting. Only http is supported.
|
config.auth_username
optional
Type: string
|
The username to authenticate with, if the forward proxy is protected
by basic authentication.
This field is referenceable, which means it can be securely stored as a
secret
in a vault. References must follow a specific format.
|
config.auth_password
optional
Type: string
|
The password to authenticate with, if the forward proxy is protected
by basic authentication.
This field is referenceable, which means it can be securely stored as a
secret
in a vault. References must follow a specific format.
|
config.https_verify
optional
Type: boolean
Default value: false
|
Whether the server certificate will be verified according to the CA certificates
specified in
lua_ssl_trusted_certificate.
|
config.x_headers
optional
Type: string
Default value: append
|
How the plugin handles the following headers:
X-Real-IP , X-Forwarded-For , X-Forwarded-Proto , X-Forwarded-Host , and X-Forwarded-Port .
The field should be set to one of the following values:
append : Append information from this hop to the headers.
transparent : Leave headers unchanged, as if not using a proxy.
delete : Remove all headers including those that should be added for this hop, as if you are the originating client.
All options respect the trusted IP setting and will ignore last hop headers if they are not from clients with trusted IPs.
|
The plugin attempts to transparently replace upstream connections made by Kong
core, sending the request instead to an intermediary forward proxy. Only
transparent HTTP proxies are supported; TLS connections (via CONNECT
)
are not supported.
Changelog
Kong Gateway 3.1.x
-
Forward Proxy: x_headers
field added. This field indicates how the plugin handles the headers
X-Real-IP
, X-Forwarded-For
, X-Forwarded-Proto
, X-Forwarded-Host
, and X-Forwarded-Port
.
The field is set to append
by default, but can be set to one of the following options:
append
: Append information from this hop to the headers.
transparent
: Leave headers unchanged, as if not using a proxy.
delete
: Remove all headers including those that should be added for this hop, as if you are the originating client.
Note that all options respect the trusted IP setting, and will ignore last hop headers if they are not from clients with trusted IPs.
Kong Gateway 2.8.x
-
Added http_proxy_host
, http_proxy_port
, https_proxy_host
, and
https_proxy_port
configuration parameters for mTLS support.
These parameters replace the proxy_port
and proxy_host
fields, which
are now deprecated and planned to be removed in a future release.
-
The auth_password
and auth_username
configuration fields are now marked as
referenceable, which means they can be securely stored as
secrets
in a vault. References must follow a specific format.
Kong Gateway 2.7.x
- Added
auth_username
and auth_password
parameters for proxy authentication.