Skip to main content

​
Overview

From Gateway 3.20.0, networking is configured per listener with GATEWAY_LISTENER_<NAME>_* variables. The global GATEWAY_PORT_*, GATEWAY_ADVERTISED_HOST, GATEWAY_ROUTING_MECHANISM and GATEWAY_SECURITY_PROTOCOL variables — the legacy network configuration — are deprecated and will be removed in Gateway 3.23. This guide shows how to switch an existing deployment to listener configuration. For how the legacy mode behaves and the full deprecated variable reference, see Legacy network configuration. Listener configuration removes the inference behavior of legacy network configuration — you set every relevant value explicitly.

​
Map legacy variables to listener variables

The legacy network variables internally create a single listener named DEFAULT. Use this mapping as a reference:
Legacy variableListener equivalent
GATEWAY_BIND_HOSTGATEWAY_LISTENER_<NAME>_BIND_ADDRESS
GATEWAY_ADVERTISED_HOSTGATEWAY_LISTENER_<NAME>_ADVERTISED_HOST
GATEWAY_PORT_START and GATEWAY_PORT_COUNTGATEWAY_LISTENER_<NAME>_PORTS
GATEWAY_ADVERTISED_SNI_PORTGATEWAY_LISTENER_<NAME>_PORTS (use advertised:local format)
GATEWAY_ROUTING_MECHANISMGATEWAY_LISTENER_<NAME>_ROUTING (host is now called sni)
GATEWAY_SECURITY_PROTOCOLGATEWAY_LISTENER_<NAME>_SECURITY_PROTOCOL
GATEWAY_ADVERTISED_HOST_PREFIX and GATEWAY_SNI_HOST_SEPARATORGATEWAY_LISTENER_<NAME>_ADVERTISED_HOST_PATTERN and GATEWAY_LISTENER_<NAME>_BOOTSTRAP_HOST_PATTERN
GATEWAY_SSL_CLIENT_AUTHGATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH
The following globals still apply to all listeners and don’t change: GATEWAY_SECURITY_MODE, GATEWAY_ACL_ENABLED, GATEWAY_SSL_KEY_STORE_*, GATEWAY_SSL_TRUST_STORE_*, and all KAFKA_* connection variables.
If your deployment still uses a DELEGATED_SASL_PLAINTEXT or DELEGATED_SASL_SSL security protocol, migrate it first: the listener SECURITY_PROTOCOL only accepts PLAINTEXT, SSL, SASL_PLAINTEXT or SASL_SSL. Set GATEWAY_SECURITY_MODE=KAFKA_MANAGED and use the plain protocol (SASL_PLAINTEXT or SASL_SSL) on the listener. See Migrate security mode.

​
Worked example

This legacy network configuration: 
GATEWAY_BIND_HOST=0.0.0.0
GATEWAY_ADVERTISED_HOST=gateway.example.com
GATEWAY_PORT_START=6969
GATEWAY_PORT_COUNT=5
GATEWAY_ADVERTISED_SNI_PORT=443
GATEWAY_ROUTING_MECHANISM=host
GATEWAY_SECURITY_PROTOCOL=SASL_SSL
GATEWAY_ADVERTISED_HOST_PREFIX=gateway
GATEWAY_SNI_HOST_SEPARATOR=-
Becomes: 
GATEWAY_SECURITY_MODE=GATEWAY_MANAGED
GATEWAY_ACL_ENABLED=true

GATEWAY_LISTENER_DEFAULT_BIND_ADDRESS=0.0.0.0
GATEWAY_LISTENER_DEFAULT_ADVERTISED_HOST=gateway.example.com
GATEWAY_LISTENER_DEFAULT_PORTS=6969-6973:443
GATEWAY_LISTENER_DEFAULT_ROUTING=sni
GATEWAY_LISTENER_DEFAULT_SECURITY_PROTOCOL=SASL_SSL
GATEWAY_LISTENER_DEFAULT_ADVERTISED_HOST_PATTERN=gateway{{physicalCluster}}{{nodeId}}-{{advertisedHost}}
GATEWAY_LISTENER_DEFAULT_BOOTSTRAP_HOST_PATTERN=gateway{{physicalCluster}}-{{advertisedHost}}
What changed:
  • GATEWAY_PORT_START=6969 with GATEWAY_PORT_COUNT=5 maps to the port range 6969-6973.
  • The :443 suffix replaces GATEWAY_ADVERTISED_SNI_PORT=443. Gateway listens locally on ports 6969-6973 but advertises port 443 to clients.
  • GATEWAY_ADVERTISED_HOST_PREFIX and GATEWAY_SNI_HOST_SEPARATOR are replaced by explicit host patterns using template variables.

​
Behavior differences to plan for

Three behaviors change when you migrate:
  1. Security mode and ACL flag have to be set explicitly. Listener configuration does not infer GATEWAY_SECURITY_MODE or GATEWAY_ACL_ENABLED from the backing Kafka cluster. Set both:
    • GATEWAY_SECURITY_MODE to GATEWAY_MANAGED or KAFKA_MANAGED.
    • GATEWAY_ACL_ENABLED to true or false (typically true for GATEWAY_MANAGED and false for KAFKA_MANAGED).
  2. SNI host patterns have changed. The default advertised host pattern is now broker-{{physicalCluster}}-{{nodeId}}.{{advertisedHost}}. This differs from the previous default built from GATEWAY_ADVERTISED_HOST_PREFIX (default broker) and GATEWAY_SNI_HOST_SEPARATOR (default -). If your DNS records and TLS certificates match the old pattern, either update them or set the pattern explicitly to reproduce it: 
    GATEWAY_LISTENER_<NAME>_ADVERTISED_HOST_PATTERN=broker{{physicalCluster}}{{nodeId}}-{{advertisedHost}}
GATEWAY_LISTENER_<NAME>_BOOTSTRAP_HOST_PATTERN=broker{{physicalCluster}}-{{advertisedHost}}
  3. mTLS configuration is per listener. Set GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH for each listener (for example, GATEWAY_LISTENER_EXTERNAL_SSL_CLIENT_AUTH=REQUIRE). The global GATEWAY_SSL_CLIENT_AUTH is ignored in listener configuration.

​
Verify the migration

Restart Gateway and check the startup logs. Confirm that:
  • The legacy deprecation warning (Legacy environment variables detected (GATEWAY_PORT_START, etc.)) no longer appears. If it does, a legacy variable is still set — Gateway refuses to start when legacy variables and an explicit listener configuration are both present, so unset every legacy variable it names.
  • The Computed configuration block lists each listener (DEFAULT if you kept a single listener) with the ports, advertised host, routing and security protocol you intended.
For the worked example above, the block lists the DEFAULT listener (this output is from Gateway 3.20.0 and may change in later versions): 
[main] [INFO] [Bootstrap] - Computed configuration:
---
listeners:
  DEFAULT:
    security:
      protocol: "SASL_SSL"
    routing: "sni"
    ports:
    - "6969-6973:443"
    advertisedHost: "gateway.example.com"
...
Run a Kafka client against the new listener (for example, with kcat ‘s metadata list mode -L) to confirm the metadata response advertises the expected hostnames and ports.