You are browsing documentation for an older version. See the latest documentation here.
Proxy Reference
In this document, we cover Kong Gateway’s proxying capabilities by explaining its routing capabilities and internal workings in details.
Kong Gateway exposes several interfaces which can be tweaked by the following configuration properties:
-
proxy_listen
, which defines a list of addresses/ports on which Kong Gateway will accept public HTTP (gRPC, WebSocket, etc) traffic from clients and proxy it to your upstream services (8000
by default). -
admin_listen
, which also defines a list of addresses and ports, but those should be restricted to only be accessed by administrators, as they expose Kong’s configuration capabilities: the Admin API (8001
by default).Important: If you need to expose the
admin_listen
port to the internet in a production environment, secure it with authentication. -
stream_listen
, which is similar toproxy_listen
but for Layer 4 (TCP, TLS) generic proxy. This is turned off by default.
Terminology
-
client
: Refers to the downstream client making requests to Kong Gateway’s proxy port. -
upstream service
: Refers to your own API/service sitting behind Kong Gateway, to which client requests/connections are forwarded. -
Service
: Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of services would be a data transformation microservice, a billing API, etc. -
Route
: This refers to the Kong Gateway routes entity. Routes are entrypoints into Kong Gateway, and defining rules for a request to be matched, and routed to a given service. -
Plugin
: This refers to Kong Gateway “plugins”, which are pieces of business logic that run in the proxying lifecycle. Plugins can be configured through the Admin API, either globally (all incoming traffic) or on specific routes and services.
Overview
From a high-level perspective, Kong Gateway listens for HTTP traffic on its configured
proxy port(s) (8000
and 8443
by default) and L4 traffic on explicitly configured
stream_listen
ports. Kong Gateway will evaluate any incoming
HTTP request or L4 connection against the routes you have configured and try to find a matching
one. If a given request matches the rules of a specific route, Kong Gateway will
process proxying the request.
Because each route may be linked to a service, Kong Gateway will run the plugins you have configured on your route and its associated service, and then proxy the request upstream. You can manage routes via Kong Gateway’s Admin API. Routes have special attributes that are used for routing, matching incoming HTTP requests. Routing attributes differ by subsystem (HTTP/HTTPS, gRPC/gRPCS, and TCP/TLS).
Subsystems and routing attributes:
-
http
:methods
,hosts
,headers
,paths
(andsnis
, ifhttps
) -
tcp
:sources
,destinations
(andsnis
, iftls
) -
grpc
:hosts
,headers
,paths
(andsnis
, ifgrpcs
)
If you attempt to configure a route with a routing attribute it doesn’t support
(e.g., an http
route with sources
or destinations
fields), an error message
is reported:
HTTP/1.1 400 Bad Request
Content-Type: application/json
Server: kong/<x.x.x>
{
"code": 2,
"fields": {
"sources": "cannot set 'sources' when 'protocols' is 'http' or 'https'"
},
"message": "schema violation (sources: cannot set 'sources' when 'protocols' is 'http' or 'https')",
"name": "schema violation"
}
If Kong Gateway receives a request that it cannot match against any of the configured routes (or if no routes are configured), it will respond with:
HTTP/1.1 404 Not Found
Content-Type: application/json
Server: kong/<x.x.x>
{
"message": "no route and no Service found with those values"
}
How to configure a service
The Configuring a Service quickstart guide explains how Kong is configured via the Admin API.
Adding a service to Kong Gateway is done by sending an HTTP request to the Admin API:
curl -i -X POST http://localhost:8001/services/ \
-d 'name=foo-service' \
-d 'url=http://foo-service.com'
Response:
HTTP/1.1 201 Created
...
{
"connect_timeout": 60000,
"created_at": 1515537771,
"host": "foo-service.com",
"id": "d54da06c-d69f-4910-8896-915c63c270cd",
"name": "foo-service",
"path": "/",
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1515537771,
"write_timeout": 60000
}
This request instructs Kong Gateway to register a service named “foo-service”, which
points to http://foo-service.com
(your upstream).
Note: The url
argument is a shorthand argument to populate the
protocol
, host
, port
, and path
attributes at once.
Now, in order to send traffic to this service through Kong Gateway, we need to specify a route, which acts as an entry point to Kong Gateway:
curl -i -X POST http://localhost:8001/routes/ \
-d 'hosts[]=example.com' \
-d 'paths[]=/foo' \
-d 'service.id=d54da06c-d69f-4910-8896-915c63c270cd'
Response:
HTTP/1.1 201 Created
...
{
"created_at": 1515539858,
"hosts": [
"example.com"
],
"id": "ee794195-6783-4056-a5cc-a7e0fde88c81",
"methods": null,
"paths": [
"/foo"
],
"preserve_host": false,
"priority": 0,
"protocols": [
"http",
"https"
],
"service": {
"id": "d54da06c-d69f-4910-8896-915c63c270cd"
},
"strip_path": true,
"updated_at": 1515539858
}
We have now configured a route to match incoming requests matching the given
hosts
and paths
, and forward them to the foo-service
we configured, thus
proxying this traffic to http://foo-service.com
.
Kong Gateway is a transparent proxy, and it defaults to forwarding the request to your
upstream service untouched, with the exception of various headers such as
Connection
, Date
, and others as required by the HTTP specifications.
Routes and matching capabilities
Let’s now discuss how Kong Gateway matches a request against the configured routing attributes.
Kong Gateway supports native proxying of HTTP/HTTPS, TCP/TLS, and GRPC/GRPCS protocols; as mentioned earlier, each of these protocols accept a different set of routing attributes:
-
http
:methods
,hosts
,headers
,paths
(andsnis
, ifhttps
) -
tcp
:sources
,destinations
(andsnis
, iftls
) -
grpc
:hosts
,headers
,paths
(andsnis
, ifgrpcs
)
Note that all of these fields are optional, but at least one of them must be specified.
For a request to match a route:
- The request must include all of the configured fields
- The values of the fields in the request must match at least one of the configured values (While the field configurations accepts one or more values, a request needs only one of the values to be considered a match)
Let’s go through a few examples. Consider a route configured like the following:
{
"hosts": ["example.com", "foo-service.com"],
"paths": ["/foo", "/bar"],
"methods": ["GET"]
}
Some of the possible requests matching this route would look like the following:
GET /foo HTTP/1.1
Host: example.com
GET /bar HTTP/1.1
Host: foo-service.com
GET /foo/hello/world HTTP/1.1
Host: example.com
All three of these requests satisfy all the conditions set in the route definition.
However, the following requests would not match the configured conditions:
GET / HTTP/1.1
Host: example.com
POST /foo HTTP/1.1
Host: example.com
GET /foo HTTP/1.1
Host: foo.com
All three of these requests satisfy only two of configured conditions. The
first request’s path is not a match for any of the configured paths
, same for
the second request’s HTTP method, and the third request’s Host header.
Now that we understand how the routing properties work together, let’s explore each property individually.
Request header
Kong Gateway supports routing by arbitrary HTTP headers. A special case of this feature is routing by the Host header.
Routing a request based on its Host header is the most straightforward way to
proxy traffic through Kong Gateway, especially since this is the intended usage of the
HTTP Host header. Kong Gateway makes it easy to do via the hosts
field of the route
entity.
hosts
accepts multiple values, which must be comma-separated when specifying
them via the Admin API, and is represented in a JSON payload:
curl -i -X POST http://localhost:8001/routes/ \
-H 'Content-Type: application/json' \
-d '{"hosts":["example.com", "foo-service.com"]}'
Response:
HTTP/1.1 201 Created
...
But since the Admin API also supports form-urlencoded content types, you
can specify an array via the []
notation:
curl -i -X POST http://localhost:8001/routes/ \
-d 'hosts[]=example.com' \
-d 'hosts[]=foo-service.com'
Response:
HTTP/1.1 201 Created
...
To satisfy the hosts
condition of this route, any incoming request from a
client must now have its Host header set to one of:
Host: example.com
or:
Host: foo-service.com
Similarly, any other header can be used for routing:
curl -i -X POST http://localhost:8001/routes/ \
-d 'headers.region=north'
Response:
HTTP/1.1 201 Created
Incoming requests containing a Region
header set to North
are routed to
said route.
Region: North
Using wildcard hostnames
To provide flexibility, Kong Gateway allows you to specify hostnames with wildcards in
the hosts
field. Wildcard hostnames allow any matching Host header to satisfy
the condition, and thus match a given Route.
Wildcard hostnames must contain only one asterisk at the leftmost or rightmost label of the domain. For example:
-
*.example.com
would allow Host values such asa.example.com
andx.y.example.com
to match. -
example.*
would allow Host values such asexample.com
andexample.org
to match.
A complete example would look like this:
{
"hosts": ["*.example.com", "service.com"]
}
Which would allow the following requests to match this route:
GET / HTTP/1.1
Host: an.example.com
GET / HTTP/1.1
Host: service.com
The preserve_host
property
When proxying, Kong Gateway’s default behavior is to set the upstream request’s Host
header to the hostname specified in the service’s host
. The
preserve_host
field accepts a boolean flag instructing Kong Gateway not to do so.
For example, when the preserve_host
property is not changed and a route is
configured like so:
{
"hosts": ["service.com"],
"service": {
"id": "..."
}
}
A possible request from a client to Kong Gateway could be:
GET / HTTP/1.1
Host: service.com
Kong Gateway would extract the Host header value from the service’s host
property, ,
and would send the following upstream request:
GET / HTTP/1.1
Host: <my-service-host.com>
However, by explicitly configuring a route with preserve_host=true
:
{
"hosts": ["service.com"],
"preserve_host": true,
"service": {
"id": "..."
}
}
And assuming the same request from the client:
GET / HTTP/1.1
Host: service.com
Kong Gateway would preserve the Host on the client request and would send the following upstream request instead:
GET / HTTP/1.1
Host: service.com
Additional request headers
It’s possible to route requests by other headers besides Host
.
To do this, use the headers
property in your route:
{
"headers": { "version": ["v1", "v2"] },
"service": {
"id": "..."
}
}
Given a request with a header such as:
GET / HTTP/1.1
version: v1
This request will be routed through to the service. The same happens with this one:
GET / HTTP/1.1
version: v2
But this request isn’t routed to the service:
GET / HTTP/1.1
version: v3
Note: The headers
keys are a logical AND
and their values a logical OR
.
Request path
Another way for a route to be matched is via request paths. To satisfy this
routing condition, a client request’s normalized path must be prefixed with one of the
values of the paths
attribute.
For example, with a route configured like so:
{
"paths": ["/service", "/hello/world"]
}
The following requests would be matched:
GET /service HTTP/1.1
Host: example.com
GET /service/resource?param=value HTTP/1.1
Host: example.com
GET /hello/world/resource HTTP/1.1
Host: anything.com
For each of these requests, Kong Gateway detects that their normalized URL path is prefixed with
one of the routes’ paths
values. By default, Kong Gateway would then proxy the
request upstream without changing the URL path.
When proxying with path prefixes, the longest paths get evaluated first.
This allow you to define two routes with two paths: /service
and
/service/resource
, and ensure that the former does not “shadow” the latter.
Using Regex in paths
For a path to be considered a regular expression, it must be prefixed with a ~
:
paths: ["~/foo/bar$"]
Any path that isn’t prefixed with a ~
will be considered plain text:
"paths": ["/users/\d+/profile", "/following"]
For more information about how the router processes regular expressions, see performance considerations when using Expressions.
Evaluation order
The router evaluates routes using the regex_priority
field of the
Route
where a route is configured. Higher regex_priority
values
mean higher priority.
[
{
"paths": ["~/status/\d+"],
"regex_priority": 0
},
{
"paths": ["~/version/\d+/status/\d+"],
"regex_priority": 6
},
{
"paths": /version,
},
{
"paths": ["~/version/any/"],
}
]
In this scenario, Kong Gateway evaluates incoming requests against the following defined URIs, in this order:
/version/\d+/status/\d+
/status/\d+
/version/any/
/version
Routers with a large number of regexes can consume traffic intended for other rules. Regular expressions are much more expensive to build and execute and can’t be optimized easily. You can avoid creating complex regular expressions using the Router Expressions language.
If you see unexpected behavior, use the Kong debug header to help track down the source:
- In
kong.conf
, setallow_debug_header: on
. - Send
Kong-Debug: 1
in your request headers to indicate the matched route ID in the response headers for troubleshooting purposes.
As usual, a request must still match a route’s hosts
and methods
properties
as well, and Kong Gateway traverses your routes until it finds one that matches
the most rules.
Capturing groups
Capturing groups are also supported, and the matched group will be extracted from the path and available for plugins consumption. If we consider the following regex:
/version/(?<version>\d+)/users/(?<user>\S+)
And the following request path:
/version/1/users/john
Kong Gateway considers the request path a match, and if the overall route is
matched (considering other routing attributes), the extracted capturing groups
will be available from the plugins in the ngx.ctx
variable:
local router_matches = ngx.ctx.router_matches
-- router_matches.uri_captures is:
-- { "1", "john", version = "1", user = "john" }
Escaping special characters
Next, it is worth noting that characters found in Regex are often
reserved characters according to
RFC 3986 and as such,
should be percent-encoded. When configuring routes with regex paths via the
Admin API, be sure to URL encode your payload if necessary. For example,
with curl
and using an application/x-www-form-urlencoded
MIME type:
curl -i -X POST http://localhost:8001/routes \
--data-urlencode 'uris[]=/status/\d+'
Response:
HTTP/1.1 201 Created
...
Note that curl
does not automatically URL encode your payload, and note the
usage of --data-urlencode
, which prevents the +
character to be URL decoded
and interpreted as a space ` ` by Kong Gateway’s Admin API.
The strip_path
property
It may be desirable to specify a path prefix to match a route, but not
include it in the upstream request. To do so, use the strip_path
boolean
property by configuring a route like so:
{
"paths": ["/service"],
"strip_path": true,
"service": {
"id": "..."
}
}
Enabling this flag instructs Kong Gateway that when matching this route, and proceeding with the proxying to a service, it should not include the matched part of the URL path in the upstream request’s URL. For example, the following client’s request to the above route:
GET /service/path/to/resource HTTP/1.1
Host: ...
This causes Kong Gateway to send the following upstream request:
GET /path/to/resource HTTP/1.1
Host: ...
The same way, if a Regex path is defined on a route that has strip_path
enabled, the entirety of the request URL matching sequence will be stripped.
For example:
{
"paths": ["/version/\d+/service"],
"strip_path": true,
"service": {
"id": "..."
}
}
The following HTTP request matching the provided Regex path:
GET /version/1/service/path/to/resource HTTP/1.1
Host: ...
Is proxied upstream by Kong Gateway as:
GET /path/to/resource HTTP/1.1
Host: ...
Normalization behavior
To prevent trivial route match bypass, the incoming request URI from client is always normalized according to RFC 3986 before router matching occurs. Specifically, the following normalization techniques are used for incoming request URIs, which are selected because they generally do not change semantics of the request URI:
- Percent-encoded triplets are converted to uppercase. For example:
/foo%3a
becomes/foo%3A
. - Percent-encoded triplets of unreserved characters are decoded. For example:
/fo%6F
becomes/foo
. - Dot segments are removed as necessary. For example:
/foo/./bar/../baz
becomes/foo/baz
. - Duplicate slashes are merged. For example:
/foo//bar
becomes/foo/bar
.
The paths
attribute of the Route object are also normalized. It is achieved by first determining
if the path is a plain text or regex path. Based on the result, different normalization techniques
are used.
For plain text route path:
Same normalization technique as above is used, that is, methods 1 through 4.
For regex route path:
Only methods 1 and 2 are used. In addition, if the decoded character becomes a regex meta character, it will be escaped with backslash.
Kong Gateway normalizes any incoming request URI before performing router matches. As a result, any request URI sent over to the upstream services will also be in normalized form that preserves the original URI semantics.
Request HTTP method
The methods
field allows matching the requests depending on their HTTP
method. It accepts multiple values. Its default value is empty (the HTTP
method is not used for routing).
The following route allows routing via GET
and HEAD
:
{
"methods": ["GET", "HEAD"],
"service": {
"id": "..."
}
}
Such a route would be matched with the following requests:
GET / HTTP/1.1
Host: ...
HEAD /resource HTTP/1.1
Host: ...
But it would not match a POST
or DELETE
request. This allows for much more
granularity when configuring plugins on routes. For example, one could imagine
two routes pointing to the same service: one with unlimited unauthenticated
GET
requests, and a second one allowing only authenticated and rate-limited
POST
requests (by applying the authentication and rate limiting plugins to
such requests).
Request source
Note: This section only applies to TCP and TLS routes.
The sources
routing attribute allows
matching a route by a list of incoming connection IP and/or port sources.
The following route allows routing via a list of source IP/ports:
{
"protocols": ["tcp", "tls"],
"sources": [{"ip":"10.1.0.0/16", "port":1234}, {"ip":"10.2.2.2"}, {"port":9123}],
"id": "...",
}
TCP or TLS connections originating from IPs in CIDR range “10.1.0.0/16” or IP address “10.2.2.2” or Port “9123” would match such route.
Request destination
Note: This section only applies to TCP and TLS routes.
The destinations
attribute, similarly to sources
,
allows matching a route by a list of incoming connection IP and/or port, but
uses the destination of the TCP/TLS connection as routing attribute.
Request SNI
When using secure protocols (https
, grpcs
, or tls
), a Server
Name Indication can be used as a routing attribute. The following route
allows routing via SNIs:
{
"snis": ["foo.test", "example.com"],
"id": "..."
}
Incoming requests with a matching hostname set in the TLS connection’s SNI extension would be routed to this route. As mentioned, SNI routing applies not only to TLS, but also to other protocols carried over TLS - such as HTTPS and If multiple SNIs are specified in the route, any of them can match with the incoming request’s SNI. with the incoming request (OR relationship between the names).
The SNI is indicated at TLS handshake time and cannot be modified after the TLS connection has
been established. This means, for example, that multiple requests reusing the same keepalive connection
will have the same SNI hostname while performing router match, regardless of the Host
header.
has been established. This means keepalive connections that send multiple requests
will have the same SNI hostnames while performing router match
(regardless of the Host
header).
Please note that creating a route with mismatched SNI and Host
header matcher
is possible, but generally discouraged.
Matching priorities
A route may define matching rules based on its headers
, hosts
, paths
, and
methods
(plus snis
for secure routes - "https"
, "grpcs"
, "tls"
)
fields. For Kong Gateway to match an incoming request to a route, all existing fields
must be satisfied. However, Kong Gateway allows for quite some flexibility by allowing
two or more routes to be configured with fields containing the same values -
when this occurs, Kong Gateway applies a priority rule.
The rule is: when evaluating a request, Kong Gateway first tries to match the routes with the most rules.
For example, if two routes are configured like so:
{
"hosts": ["example.com"],
"service": {
"id": "..."
}
},
{
"hosts": ["example.com"],
"methods": ["POST"],
"service": {
"id": "..."
}
}
The second route has a hosts
field and a methods
field, so it is
evaluated first by Kong Gateway. By doing so, we avoid the first route “shadowing”
calls intended for the second one.
Thus, this request matches the first route:
GET / HTTP/1.1
Host: example.com
And this request matches the second one:
POST / HTTP/1.1
Host: example.com
Following this logic, if a third route was to be configured with a hosts
field, a methods
field, and a uris
field, it would be evaluated first by
Kong Gateway.
If the rule count for the given request is the same in two routes A
and
B
, then the following tiebreaker rules will be applied in the order they
are listed. Route A
will be selected over B
if:
-
A
has only “plain” Host headers andB
has one or more “wildcard” host headers -
A
has more non-Host headers thanB
. -
A
has at least one “regex” paths andB
has only “plain” paths. -
A
’s longest path is longer thanB
’s longest path. A.created_at < B.created_at
Proxying behavior
The proxying rules above detail how Kong Gateway forwards incoming requests to your upstream services. Below, we detail what happens internally between the time Kong Gateway matches an HTTP request with a registered route, and the actual forwarding of the request.
Load balancing
Kong Gateway implements load balancing capabilities to distribute proxied requests across a pool of instances of an upstream service.
You can find more information about configuring load balancing by consulting the Load Balancing Reference.
Plugins execution
Kong Gateway is extensible via “plugins” that hook themselves in the request/response lifecycle of the proxied requests. Plugins can perform a variety of operations in your environment and/or transformations on the proxied request.
Plugins can be configured to run globally (for all proxied traffic) or on specific routes and services. In both cases, you must create a plugin configuration via the Admin API.
Once a route has been matched (and its associated service entity), Kong Gateway will run plugins associated to either of those entities. Plugins configured on a route run before plugins configured on a service, but otherwise, the usual rules of plugins association apply.
These configured plugins will run their access
phase, which you can find more
information about in the Plugin development guide.
Proxying and upstream timeouts
Once Kong Gateway has executed all the necessary logic (including plugins), it is ready
to forward the request to your upstream service. This is done via Nginx’s
ngx_http_proxy_module
. You can configure the desired
timeouts for the connection between Kong Gateway and a given upstream, via the following
properties of a service:
-
connect_timeout
: defines in milliseconds the timeout for establishing a connection to your upstream service. Defaults to60000
. -
write_timeout
: defines in milliseconds a timeout between two successive write operations for transmitting a request to your upstream service. Defaults to60000
. -
read_timeout
: defines in milliseconds a timeout between two successive read operations for receiving a request from your upstream service. Defaults to60000
.
Kong Gateway will send the request over HTTP/1.1, and set the following headers:
-
Host: <your_upstream_host>
, as previously described in this document. -
Connection: keep-alive
, to allow for reusing the upstream connections. -
X-Real-IP: <remote_addr>
, where$remote_addr
is the variable bearing the same name provided by ngx_http_core_module. Please note that the$remote_addr
is likely overridden by ngx_http_realip_module. -
X-Forwarded-For: <address>
, where<address>
is the content of$realip_remote_addr
provided by ngx_http_realip_module appended to the request header with the same name. -
X-Forwarded-Proto: <protocol>
, where<protocol>
is the protocol used by the client. In the case where$realip_remote_addr
is one of the trusted addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the$scheme
variable provided by ngx_http_core_module will be used. -
X-Forwarded-Host: <host>
, where<host>
is the host name sent by the client. In the case where$realip_remote_addr
is one of the trusted addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the$host
variable provided by ngx_http_core_module will be used. -
X-Forwarded-Port: <port>
, where<port>
is the port of the server which accepted a request. In the case where$realip_remote_addr
is one of the trusted addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the$server_port
variable provided by ngx_http_core_module will be used. -
X-Forwarded-Prefix: <path>
, where<path>
is the path of the request which was accepted by Kong Gateway. In the case where$realip_remote_addr
is one of the trusted addresses, the request header with the same name gets forwarded if provided. Otherwise, the value of the$request_uri
variable (with the query string stripped) provided by ngx_http_core_module will be used.Note: Kong Gateway returns
"/"
for an empty path, but it doesn’t do any other normalization on the request path.
All the other request headers are forwarded as-is by Kong Gateway.
One exception to this is made when using the WebSocket protocol. If so, Kong Gateway sets the following headers to allow for upgrading the protocol between the client and your upstream services:
Connection: Upgrade
Upgrade: websocket
More information on this topic is covered in the Proxy WebSocket traffic section.
Errors and retries
Whenever an error occurs during proxying, Kong Gateway uses the underlying Nginx retries mechanism to pass the request on to the next upstream.
There are two configurable elements here:
-
The number of retries: this can be configured per service using the
retries
property. See the Admin API for more details on this. -
What exactly constitutes an error: here Kong Gateway uses the Nginx defaults, which means an error or timeout occurring while establishing a connection with the server, passing a request to it, or reading the response headers.
The second option is based on Nginx’s
proxy_next_upstream
directive. This option is not
directly configurable through Kong Gateway, but can be added using a custom Nginx
configuration. See the configuration reference for
more details.
Response
Kong Gateway receives the response from the upstream service and sends it back to the
downstream client in a streaming fashion. At this point, Kong Gateway executes
subsequent plugins added to the route and/or service that implement a hook in
the header_filter
phase.
Once the header_filter
phase of all registered plugins has been executed, the
following headers are added by Kong Gateway and the full set of headers be sent to
the client:
-
Via: kong/x.x.x
, wherex.x.x
is the Kong Gateway version in use -
X-Kong-Proxy-Latency: <latency>
, wherelatency
is the time in milliseconds between Kong Gateway receiving the request from the client and sending the request to your upstream service. -
X-Kong-Upstream-Latency: <latency>
, wherelatency
is the time in milliseconds that Kong Gateway was waiting for the first byte of the upstream service response.
Once the headers are sent to the client, Kong Gateway starts executing
registered plugins for the route and/or service that implement the
body_filter
hook. This hook may be called multiple times, due to the
streaming nature of Nginx. Each chunk of the upstream response that is
successfully processed by such body_filter
hooks is sent back to the client.
You can find more information about the body_filter
hook in the Plugin
development guide.
Configuring a fallback route
As a practical use-case and example of the flexibility offered by Kong Gateway’s
proxying capabilities, let’s try to implement a “fallback route”, so that in
order to avoid Kong Gateway responding with an HTTP 404
, “no route found”, we can
catch such requests and proxy them to a special upstream service, or apply a
plugin to it (such a plugin could, for example, terminate the request with a
different status code or response without proxying the request).
Here is an example of such a fallback route:
{
"paths": ["/"],
"service": {
"id": "..."
}
}
As you can guess, any HTTP request made to Kong Gateway would actually match this
route, since all URIs are prefixed by the root character /
. As we know from
the Request path section, the longest URL paths are
evaluated first by Kong Gateway, so the /
path will eventually be evaluated last by
Kong Gateway, and effectively provide a “fallback” route, only matched as a last
resort. You can then send traffic to a special service or apply any plugin you
wish on this route.
Configuring TLS for a route
Kong Gateway provides a way to dynamically serve TLS certificates on a per-connection basis. TLS certificates are directly handled by the core, and configurable via the Admin API. Clients connecting to Kong Gateway over TLS must support the Server Name Indication extension to make use of this feature.
TLS certificates are handled by two resources in the Kong Gateway Admin API:
-
/certificates
, which stores your keys and certificates. -
/snis
, which associates a registered certificate with a Server Name Indication.
You can find the documentation for those two resources in the Admin API Reference.
Here is how to configure a TLS certificate on a given route: first, upload your TLS certificate and key via the Admin API:
curl -i -X POST http://localhost:8001/certificates \
-F "cert=@/path/to/cert.pem" \
-F "key=@/path/to/cert.key" \
-F "snis=*.tls-example.com,other-tls-example.com"
Response:
HTTP/1.1 201 Created
...
The snis
form parameter is a convenience parameter. Under the hood, it directly inserts an SNI and
associates the uploaded certificate to it.
Note that one of the SNI names defined in snis
above contains a wildcard
(*.tls-example.com
). An SNI may contain a single wildcard in the leftmost (prefix) or
rightmost (suffix) position. This can be useful when maintaining multiple subdomains. A
single sni
configured with a wildcard name can be used to match multiple
subdomains, instead of creating an SNI for each.
Valid wildcard positions are mydomain.*
, *.mydomain.com
, and *.www.mydomain.com
.
A default certificate can be added using the following parameters in Kong Gateway configuration:
Or, by dynamically configuring the default certificate with an SNI of *
:
curl -i -X POST http://localhost:8001/certificates \
-F "cert=@/path/to/default-cert.pem" \
-F "key=@/path/to/default-cert.key" \
-F "snis=*"
Response:
HTTP/1.1 201 Created
...
Matching of snis
respects the following priority:
- Exact SNI matching certificate
- Search for a certificate by prefix wildcard
- Search for a certificate by suffix wildcard
- Search for a certificate associated with the SNI
*
- The default certificate on the file system
You must now register the following route within Kong Gateway. We match requests to this route using only the Host header for convenience:
curl -i -X POST http://localhost:8001/routes \
-d 'hosts=prefix.tls-example.com,other-tls-example.com' \
-d 'service.id=d54da06c-d69f-4910-8896-915c63c270cd'
Response:
HTTP/1.1 201 Created
...
You can now expect the route to be served over HTTPS by Kong Gateway:
curl -i https://localhost:8443/ \
-H "Host: prefix.tls-example.com"
Response:
HTTP/1.1 200 OK
...
When establishing the connection and negotiating the TLS handshake, if your
client sends prefix.tls-example.com
as part of the SNI extension, Kong Gateway serves
the cert.pem
certificate previously configured. This is the same for both HTTPS and
TLS connections.
Restricting the client protocol
Routes have a protocols
property to restrict the client protocol they should
listen for. This attribute accepts a set of values, which can be "http"
,
"https"
, "grpc"
, "grpcs"
, "tcp"
, or "tls"
.
A Route with http
and https
will accept traffic in both protocols.
{
"hosts": ["..."],
"paths": ["..."],
"methods": ["..."],
"protocols": ["http", "https"],
"service": {
"id": "..."
}
}
Not specifying any protocol has the same effect, since routes default to
["http", "https"]
.
However, a route with only https
would only accept traffic over HTTPS. It
would also accept unencrypted traffic if TLS termination previously
occurred from a trusted IP. TLS termination is considered valid when the
request comes from one of the configured IPs in
trusted_ips and if the X-Forwarded-Proto: https
header is set:
{
"hosts": ["..."],
"paths": ["..."],
"methods": ["..."],
"protocols": ["https"],
"service": {
"id": "..."
}
}
If a route such as the above matches a request, but that request is in plain-text without valid prior TLS termination, Kong Gateway responds with:
HTTP/1.1 426 Upgrade Required
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: Upgrade
Upgrade: TLS/1.2, HTTP/1.1
Server: kong/x.y.z
{"message":"Please use HTTPS protocol"}
It’s possible to create routes for raw TCP (not necessarily HTTP)
connections by using "tcp"
in the protocols
attribute:
{
"hosts": ["..."],
"paths": ["..."],
"methods": ["..."],
"protocols": ["tcp"],
"service": {
"id": "..."
}
}
Similarly, we can create routes which accept raw TLS traffic (not necessarily HTTPS) with
the "tls"
value:
{
"hosts": ["..."],
"paths": ["..."],
"methods": ["..."],
"protocols": ["tls"],
"service": {
"id": "..."
}
}
A route with only TLS
would only accept traffic over TLS.
It is also possible to accept both TCP and TLS simultaneously:
{
"hosts": ["..."],
"paths": ["..."],
"methods": ["..."],
"protocols": ["tcp", "tls"],
"service": {
"id": "..."
}
}
For L4 TLS proxy to work, it is necessary to create route that accepts
the tls
protocol
, as well as having the appropriate TLS certificate
uploaded and their sni
attribute properly set to match incoming connection’s
SNI. Please refer to the Configuring TLS for a Route
section above for instructions on setting this up.
Proxy WebSocket traffic
Kong Gateway supports WebSocket traffic thanks to the underlying Nginx implementation. When you want to establish a WebSocket connection between a client and your upstream services through Kong Gateway, you must establish a WebSocket handshake. This is done via the HTTP Upgrade mechanism. This is what your client request made to Kong Gateway would look like:
GET / HTTP/1.1
Connection: Upgrade
Host: my-websocket-api.com
Upgrade: WebSocket
This makes Kong Gateway forward the Connection
and Upgrade
headers to your
upstream service, instead of dismissing them due to the hop-by-hop nature of a
standard HTTP proxy.
WebSocket proxy modes
There are two methods for proxying WebSocket traffic in Kong Gateway:
- HTTP(S) services and routes
- WS(S) services and routes
HTTP(S) services and routes
Services and routes using the http
and https
protocols are fully capable of
handling WebSocket connections with no special configuration. With this method,
WebSocket sessions behave identically to regular HTTP requests, and all of the
request/response data is treated as an opaque stream of bytes.
services:
- name: my-http-websocket-service
protocol: http
host: 1.2.3.4
port: 80
path: /
routes:
- name: my-http-websocket-route
protocols:
- http
- https
WS(S) services and routesAvailable with Kong Gateway Enterprise subscription - Contact Sales
In addition to HTTP services and routes, Kong Gateway Enterprise includes
the ws
(WebSocket-over-http) and wss
(WebSocket-over-https) options for
service protocol
and route protocols
. In contrast to http
/https
, ws
and wss
services have full control over the underlying WebSocket connection.
This means that they can use WebSocket plugins and the WebSocket PDK to
perform business logic on a per-message basis (message validation, accounting,
rate-limiting, etc).
services:
- name: my-dedicated-websocket-service
protocol: ws
host: 1.2.3.4
port: 80
path: /
routes:
- name: my-dedicated-websocket-route
protocols:
- ws
- wss
Note: Decoding and encoding WebSocket messages comes with a non-zero amount of performance overhead when compared with the protocol-agnostic behavior of
http(s)
services. If your API does not need the extra capabilities provided by aws(s)
service, it’s recommended that you use anhttp(s)
service instead.
WebSocket and TLS
Regardless of which service/route protocols are in use (http(s)
or ws(s)
),
Kong Gateway will accept plain and TLS WebSocket connections on its
respective http
and https
ports. To enforce TLS connections from clients,
set the protocols
property of the route to https
or wss
only.
When setting up the service to point to your upstream WebSocket service, you should carefully pick the protocol you want to use between Kong Gateway and the upstream.
If you want to use TLS, your upstream WebSocket service must be defined using
the https
(or wss
) protocol in the service protocol
property and the
proper port (usually 443). To connect without TLS, then the http
(or ws
)
protocol and port (usually 80) should be used in protocol
instead.
If you want Kong Gateway to terminate TLS, you can accept
https
/wss
only from the client, but proxy to the upstream service over
plain text (http
or ws
).
Proxy gRPC traffic
gRPC proxying is natively supported in Kong Gateway. In order to manage gRPC services and proxy gRPC requests with Kong Gateway, create services and routes for your gRPC services.
Only observability and logging plugins are supported with gRPC - plugins known to be supported with gRPC have “grpc” and “grpcs” listed under the supported protocols field in their Kong Hub page - for example, check out the File Log plugin’s page.
Proxy TCP/TLS traffic
TCP and TLS proxying is natively supported in Kong Gateway.
In this mode, data of incoming connections reaching the stream_listen
endpoints will
be passed through to the upstream. It is possible to terminate TLS connections
from clients using this mode as well.
To use this mode, aside from defining stream_listen
, appropriate route/service
object with protocol types of tcp
or tls
should be created.
If TLS termination by Kong Gateway is desired, the following conditions must be met:
- The Kong Gateway port where TLS connection connects to must have the
ssl
flag enabled - A certificate/key that can be used for TLS termination must be present inside Kong Gateway, as shown in Configuring TLS for a Route
Kong Gateway will use the connecting client’s TLS SNI server name extension to find the appropriate TLS certificate to use.
On the service side, depends on whether connection between Kong Gateway and the upstream
service need to be encrypted, tcp
or tls
protocol types can be set accordingly.
This means all of the below setup are supported in this mode:
- Client <- TLS -> Kong <- TLS -> Upstream
- Client <- TLS -> Kong <- Cleartext -> Upstream
- Client <- Cleartext -> Kong <- TLS -> Upstream
Note: In L4 proxy mode, only plugins that has tcp
or tls
in the supported
protocol list are supported. This list can be found in their respective documentation
on Kong Hub.
Proxy TLS passthrough traffic
Kong Gateway supports proxying a TLS request without terminating or known as SNI proxy.
Kong Gateway uses the connecting client’s TLS SNI extension to find the matching Route and Service and forward the complete TLS request upstream, without decrypting the incoming TLS traffic.
In this mode, you need to:
- Create a route object with the protocol
tls_passthrough
, and thesnis
field set to one or more SNIs. - Set the corresponding service object’s protocol to
tcp
. - Send requests to a port that has the
ssl
flag in itsstream_listen
directive.
Separate SNI and Certificate entities aren’t required and won’t be used.
Routes are not allowed to match tls
and tls_passthrough
protocols at same time.
However, the same SNI is allowed to match tls
and tls_passthrough
in different
routes.
It’s also possible to set route to tls_passthrough
and service to tls
. In this
mode, the connection to the upstream will be TLS-encrypted twice.
Note: To run any plugins in this mode, the plugin’s
protocols
field must includetls_passthrough
.
Conclusion
Through this guide, we hope you gained knowledge of the underlying proxying mechanism of Kong Gateway, from how does a request match a route to be routed to its associated service, on to how to allow for using the WebSocket protocol or setup dynamic TLS certificates.
This website is open-source and can be found at github.com/Kong/docs.konghq.com. Feel free to provide feedback to this document there, or propose improvements!
If you haven’t already, we suggest that you also read the Load balancing Reference, as it closely relates to the topic we just covered.