Set up multiple listeners

Expose Conduktor Gateway through multiple listeners — for example, an internal plaintext endpoint alongside an external SASL_SSL endpoint.

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.

Enable TLS for SSL and SASL_SSL listeners in the helm chart

The example above uses SASL_SSL on the external listener. On the Conduktor Gateway Helm chart, any listener that uses SSL or SASL_SSL requires tls.enable: true (or tls.certManager.enabled: true), otherwise the chart fails validation:

tls.enable or tls.certManager.enabled must be set when any listener uses SSL or SASL_SSL securityProtocol

Setting GATEWAY_SSL_KEY_STORE_PATH through gateway.env alone does not satisfy this — it works at runtime but not at chart render time.

tls:
  enable: true
  keystore:
    secretRef: "conduktor-gateway-ssl-certificate"
    keystoreKey: "keystore.jks"
    keystoreFile: "keystore.jks"

With tls.keystore.secretRef set, tls.enable: true generates these container env vars and mounts the keystore secret at /etc/gateway/tls/:

Env var	Value
GATEWAY_SSL_KEY_STORE_PATH	/etc/gateway/tls/<keystoreFile>
GATEWAY_SSL_KEY_TYPE	jks
GATEWAY_SSL_KEY_STORE_PASSWORD	Set only if tls.keystore.passwordSecretRef is set

These are explicit container env vars, so they override any same-named value from gateway.env.

Under tls.enable: true, the chart generates GATEWAY_SSL_KEY_STORE_PASSWORD only when tls.keystore.passwordSecretRef is set. Without it, supply the GATEWAY_SSL_KEY_STORE_PASSWORD environment variable yourself through gateway.env or extraSecretEnvVars.

Use cert-manager instead

To source the keystore from cert-manager rather than a static secret, set tls.certManager.enabled: true. This also satisfies the SSL/SASL_SSL requirement. tls.enable and tls.certManager.enabled are mutually exclusive — the chart fails validation if both are true.

Unlike tls.enable, cert-manager always supplies the keystore password from its password secret, so the chart also generates GATEWAY_SSL_KEY_STORE_PASSWORD and GATEWAY_SSL_KEY_PASSWORD — you don’t set them yourself.

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.

Related resources

• Configure Gateway listeners
• Configure listener security
• Set up SNI routing
• Configure Gateway load balancing
• Gateway environment variables