See what makes Kong the fastest, most-adopted API gateway
Check out the latest Kong feature releases and updates
Single platform for SaaS end-to-end connectivity
Enterprise service mesh based on Kuma and Envoy
Collaborative API design platform
How to Scale High-Performance APIs and Microservices
Call for speakers & sponsors, Kong API Summit 2023!
4 MIN READ
With Kong 1.0 users are now able to control TCP (Transport Control Protocol) traffic. Learn about how we added TCP support, and how you can try it out.
TCP traffic powers email, file transfer, ssh, and many other common types of traffic that can’t be handled by a layer 7 proxy. Our expansion to layer 4 will enable you to connect even more of your services using Kong.
When we were designing the ability to deploy Kong as a service mesh, we wanted to build a system that could connect all our users’ services, running on any infrastructure, written in any language, and architected in any pattern. Part of fulfilling this promise meant moving down the Open Systems Interconnection (OSI) stack to cover services that communicate using protocols other than HTTP. We wanted Kong to be able to handle all types of TCP traffic when deployed either as an API gateway or in a mesh pattern. With our sponsorship of OpenResty’s stream support, we were able to add user-facing support for TCP traffic to Kong.
Our new stream_listen configuration option allows users to select the IPs and ports where Kong’s stream mode should listen for TCP traffic. Kong automatically terminates Transport Layer Security (TLS) for incoming TLS traffic, and depending on service configuration you can have Kong encrypt outbound connections with TLS or not. Using Kong’s Server Name Indication (SNI) and certificate entities, users can now also configure their own TLS certificates. One of the major use cases for Kong’s TCP support is TLS termination.
Kong’s extensibility with plugins is a big reason that users choose Kong over other API Gateways or service meshes. TCP traffic handling is still in its early days, and Kong 1.0 didn’t ship with any TCP-supporting plugins. But, users are already able to write their own custom plugins that apply to TCP traffic. Writing a TCP plugin is a little different to a traditional Kong HTTP plugin. Instead of “rewrite”, “access”, “header” and “body” phases, TCP plugins will have a “preread” phase.
TCP support requires some customizations that Kong has made for OpenResty. If you’re compiling your own OpenResty from source, apply Kong’s openresty-patches to be able to use this new functionality. Kongs packages and images already come with these patches applied.
Another thing to watch out for is that you should *not* try to use the Nginx SSL listener directive for stream ports. Kong decides to terminate TLS via it’s own mechanisms instead.
The following is a runnable example using Docker to terminate TLS traffic before sending it to tcpbin.
# Start up your normal Postgres database and run kong migrations
# See https://docs.konghq.com/install/docker/ for more information
docker network create kong-net
docker run -d --name kong-database \
-e "POSTGRES_USER=kong" \
-e "POSTGRES_DB=kong" \
docker run --rm \
-e "KONG_PG_HOST=kong-database" \
kong:1.0.3-alpine kong migrations bootstrap
# Start kong with stream_listen
docker run \
-e "KONG_PG_HOST=kong-database" \
-e "KONG_PROXY_ACCESS_LOG=/dev/stdout" \
-e "KONG_ADMIN_ACCESS_LOG=/dev/stdout" \
-e "KONG_PROXY_ERROR_LOG=/dev/stderr" \
-e "KONG_ADMIN_ERROR_LOG=/dev/stderr" \
-e "KONG_ADMIN_LISTEN=0.0.0.0:8001" -p 8001:8001 \
-e "KONG_STREAM_LISTEN=0.0.0.0:5555" -p 5555:5555 \
# Add a service and route
curl localhost:8001/services -d name=tcpbin-echo -d url=tcp://22.214.171.124:30000
curl localhost:8001/services/tcpbin-echo/routes -d protocols=tls -d snis=tlsbin-example
# Try out the service (it'll do a TLS handshake then echo your input)
openssl s_client -connect localhost:5555 -servername tlsbin-example
Here are just a few of the improvements to TCP support that you can look forward to in future versions of Kong.
At the moment Kong will unconditionally try to terminate TLS if the traffic looks like a valid TLS ClientHello. We want to make this configurable on a per-route basis, which will include the ability to terminate or not based on SNI.
The next Kong release will include support for custom Nginx directives for the stream module. You can check out that work in the PR here.
In the future, the Kong Plugin Development Kit (PDK) will include more support for TCP data. Currently, to write many types of TCP plugins you need to delve into sparsely documented internal structures. We will slowly be exposing more fields and making it easier to write your own Kong TCP plugins. We’ll also be updating any appropriate Kong-supported plugins to work with TCP.
If you’re a plugin maintainer and want to add TCP support, or if you have any questions about TCP support in Kong, please get in touch with us through our community forum, Kong Nation.
Get the latest version of Kong