Skip to main content
A single Gateway can expose Kafka clients through multiple listeners, each with its own routing strategy, security protocol and network bindings. Use multiple listeners when your clients reach Gateway through more than one endpoint.
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.

​
When to use multiple listeners

Typical cases:
  • Internal and external endpoints with different security. For example, PLAINTEXT for internal services on a private network, SASL_SSL for external clients over the public internet.
  • Kubernetes deployments with separate services. A ClusterIP service for in-cluster traffic and a LoadBalancer service for external traffic, each mapped to a different listener.
  • Distinct client populations with different security requirements. For example, a legacy fleet on SASL_PLAINTEXT migrating gradually to a new SASL_SSL listener.
If a single endpoint covers your needs, a single listener is simpler and sufficient.

​
Configure two listeners

Add each listener with its own GATEWAY_LISTENER_<NAME>_* block. The example below defines an EXTERNAL listener with SNI routing and SASL_SSL, and an INTERNAL listener with port routing and PLAINTEXT. 
GATEWAY_SECURITY_MODE=GATEWAY_MANAGED
GATEWAY_ACL_ENABLED=true

# External listener - encrypted with authentication
GATEWAY_LISTENER_EXTERNAL_SECURITY_PROTOCOL=SASL_SSL
GATEWAY_LISTENER_EXTERNAL_ROUTING=sni
GATEWAY_LISTENER_EXTERNAL_PORTS=9092
GATEWAY_LISTENER_EXTERNAL_ADVERTISED_HOST_PATTERN=broker-{{physicalCluster}}-{{nodeId}}.kafka.<YOUR_DOMAIN>

# Internal listener - plaintext for internal services
GATEWAY_LISTENER_INTERNAL_SECURITY_PROTOCOL=PLAINTEXT
GATEWAY_LISTENER_INTERNAL_ROUTING=port
GATEWAY_LISTENER_INTERNAL_PORTS=19092-19095
GATEWAY_LISTENER_INTERNAL_ADVERTISED_HOST=gateway.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.

​
Constraints

Some configuration stays global across all listeners:
  • Shared SSL keystore and truststore. All listeners share the same keystore and truststore. To serve different certificates per listener, include all of them in the global keystore — Gateway selects the right one based on SNI during the TLS handshake.
  • Shared SASL mechanisms. All SASL listeners share the same set of enabled SASL mechanisms. You can’t enable different mechanisms per listener (for example, OAUTHBEARER-only for external, PLAIN-only for internal).
  • Global security mode. All listeners share the same GATEWAY_SECURITY_MODE. You can’t mix GATEWAY_MANAGED and KAFKA_MANAGED across listeners. If your use case requires both modes, deploy separate Gateway instances.
  • Internal load balancing is global. Internal load balancing is a global setting. When enabled, all listeners have to share the same advertised host. If listeners have different advertised hosts, disable internal load balancing or Gateway will fail to start.

​
Verify the configuration

Gateway logs the computed configuration at startup, including all registered listeners, their ports and routing mechanisms. Check the startup logs: 
docker logs <YOUR_GATEWAY_CONTAINER>
Look for listener entries in the Computed configuration output. For the example above, the block lists both listeners (this output is from Gateway 3.20.0 and may change in later versions): 
[main] [INFO] [Bootstrap] - Computed configuration:
---
listeners:
  EXTERNAL:
    security:
      protocol: "SASL_SSL"
    routing: "sni"
    ports:
    - "9092"
  INTERNAL:
    security:
      protocol: "PLAINTEXT"
    routing: "port"
    ports:
    - "19092-19095"
...
Each listener should appear with its name, ports, security protocol and routing mechanism. If a listener is missing or has unexpected values, check that the environment variables follow the GATEWAY_LISTENER_<NAME>_<PROPERTY> naming pattern and that the listener name contains only alphanumeric characters. Run a Kafka client against each listener to confirm the metadata response advertises the expected hostnames and ports for that listener.