Overview
SNI routing reduces the number of Gateway ports exposed to clients. Unlike port mapping, which differentiates brokers based on the port a client connects to, SNI routing distinguishes brokers by the hostname the client wants to connect to. This allows Gateway to expose a single port while directing traffic to the appropriate broker based on the client’s requested hostname. This is particularly useful if you are:- Experiencing a high administrative overhead for managing multiple ports.
- Restricted by your security department in the number of ports you can expose.
Context about client connection
To understand the different steps required to set up SNI routing, let’s break it down into the connection steps each client would take:- Connect to Gateway advertised host
- Retrieve how to reach the right broker for each topic partition in the metadata returned by Gateway
- Directly connect to the desired broker through Gateway
- Define which ports we need to configure for Gateway to listen on and return in the metadata.
- Make sure Gateway handles the TLS termination.
- Prepare the keystore certificate for Gateway to include the Gateway hostname as well as a SAN for each broker in the cluster. Alternatively, wildcards
*
can be used in the SAN, if supported by your issuer and security team. - Add the same entries to the DNS server to allow the clients to be properly routed to the Gateway advertised host and Kafka brokers through Gateway.
- Configure Gateway to use the SNI routing mechanism.
In order to keep Gateway as stateless as possible, we do not store the metadata internally. We simply pass it on to the client. This means that the metadata will be refreshed every time a client asks for it (e.g. when a new client connects or when the connection refreshes).
Set up SNI routing
1. Define ports
With Gateway using SNI routing, you only expose a single port for all your brokers. However, depending on your infrastructure, you may want to differentiate between the port the Gateway container listens on and the port returned in the metadata for clients to connect. This could be the case if you’re using a load balancer:
GATEWAY_PORT_START
environment variable.
To configure the port that is returned in the metadata, you can use the GATEWAY_ADVERTISED_SNI_PORT
. By default, this port will be the same as the GATEWAY_PORT_START
.
2. TLS termination
When Gateway is set up to act as the SNI router, it has to terminate (i.e., decrypt) the incoming TLS connections because:-
SNI information requires TLS handling: this information is transmitted in the TLS
ClientHello
handshake. To forward network requests based on TLS SNI, Gateway has to participate in the TLS handshake to extract the server name indication. If TLS is terminated upstream of Gateway, the SNI information is no longer available. - Kafka protocol inspection requires decryption: even though SNI information is available in the un-encrypted portion of the TLS handshake, Gateway has to decrypt the traffic to apply its functionality, which operates on the Kafka protocol layer. Since Gateway needs to inspect, modify or route based on Kafka protocol messages (API keys, topics, etc.), TLS passthrough is not possible.
- handle the TLS handshake with the client and
- have a valid keystore certificate for the advertised host (and all the brokers in the cluster).
3. Prepare Gateway’s keystore certificate
The keystore certificate for Gateway with SNI routing needs to include the Gateway advertised host, as well as a SAN for each advertised broker in the cluster. Alternatively, wildcards*
can be used in the SAN, if supported by your issuer and security team.
If you need to detail all the advertised brokers in the Gateway keystore, here is the format returned by Gateway for each broker:

- The advertised host prefix, which is customizable with
GATEWAY_ADVERTISED_HOST_PREFIX
and defaults tobroker
- The Kafka cluster ID in Gateway, which is not customizable and defaults to
main
. - The broker ID in the Kafka cluster, which is unique for each broker and retrieved directly from your Kafka cluster.
- The SNI host separator, which is customizable with
GATEWAY_SNI_HOST_SEPARATOR
and defaults to-
. - The advertised host, which is customizable with
GATEWAY_ADVERTISED_HOST
.
gateway.conduktor.sni-demo.local
and we have a Kafka cluster with 3 brokers with IDs 1, 2, and 3. The SANs for the certificate would be:
4. Configure DNS
Next, create DNS entries to allow clients to be properly routed to the Gateway advertised host and Kafka brokers through Gateway.5. Configure Gateway
Here’s the minimum configurations required, depending on the security protocol you want to use for your clients to connect to Gateway.This is in addition to the
KAFKA_
properties required for Gateway to connect to the Kafka cluster.Please check the list of environment variables for Gateway SSL configuration and Gateway SNI routing configuration.Debug and troubleshoot
You can use Console’s Brokers tab to view the advertised listeners of a Gateway once the initial connection and authentication are successful:
LOG4J2_IO_CONDUKTOR_PROXY_NETWORK_LEVEL
to DEBUG
might be helpful when debugging issues.
For more details, see a comprehensive SNI routing troubleshooting guide