Skip to main content
Per-listener configuration with GATEWAY_LISTENER_<NAME>_* variables is available from Gateway 3.20.0. On earlier versions, networking is configured with the global variables described in Legacy network configuration. To move an existing deployment over, see Migrate to listener configuration.
Kafka clients connect to Conduktor Gateway through listeners. A listener is a network endpoint with its own routing strategy, network bindings and security protocol. A simple deployment uses a single listener; containerized environments often expose two (internal and external).

​
Choose a routing strategy

A listener routes clients to brokers in one of two ways: Choose port routing if your environment:
  • doesn’t require TLS encryption
  • has flexible network port management capabilities
  • prefers a simpler, straightforward configuration without DNS complexities
Choose SNI routing if your environment:
  • requires TLS-encrypted connections for secure communication
  • faces challenges managing multiple network ports
  • seeks a scalable solution with easier routing management through DNS and host names
For local development and testing, you can skip listener configuration entirely. With no listener or networking variables set, Gateway runs in zero-config mode: it creates a default port-routing listener and infers the security mode and protocol from the backing Kafka cluster (with ACLs disabled). Don’t use it in production.

​
Define a listener

Define a listener using environment variables with the pattern GATEWAY_LISTENER_<NAME>_<PROPERTY>, where <NAME> is a label you choose (for example, DEFAULT, EXTERNAL, INTERNAL).
Listener names have to start with a letter and contain only alphanumeric characters. Underscores are reserved as delimiters in GATEWAY_LISTENER_<NAME>_<PROPERTY>, so a name like MY_LISTENER would be ambiguous. Gateway only recognizes variables whose <NAME> matches this pattern — variables using any other name are ignored, and the listener is silently not created.

​
Set up a listener with port routing

With port routing, Gateway assigns one port per Kafka broker. Clients connect to the appropriate port to reach the broker they need. The recommended number of ports in production is double the number of brokers to cover cluster growth. An example single-listener configuration:
Gateway maps ports to broker IDs in order from GATEWAY_MIN_BROKERID. Set it to the lowest broker ID in your Kafka cluster and provide enough ports for every broker. Above, brokers 1, 2, 3 map to ports 9092, 9093, 9094, with 9095-9097 as headroom for cluster growth. We recommend SNI routing when broker IDs are not sequential and stable. For example, a three-broker cluster with IDs 100, 200, 300 and GATEWAY_MIN_BROKERID=100 would need a port range covering 100 through 300, and would fail if broker ID 400 were introduced. For the full list of listener environment variables, see the environment variables reference.

​
Set up a listener with SNI routing

With SNI routing, Gateway listens on a single port and routes traffic based on the hostname in the TLS handshake. SNI routing requires a TLS-based security protocol (SSL or SASL_SSL) and proper DNS and TLS certificates for each broker hostname. Follow the SNI routing tutorial for the step-by-step setup, including certificate preparation and DNS configuration.

​
Advertised host and load balancing

A listener’s advertised host is what Gateway returns to clients in metadata responses. When Gateway sits behind a load balancer, the advertised host has to point at the load balancer rather than at the Gateway pod, otherwise clients will try to bypass it. Configure Gateway load balancing before finalizing the listener’s advertised host.