Before Gateway 3.20.0, Gateway was configured with global GATEWAY_PORT_*, GATEWAY_ADVERTISED_HOST, GATEWAY_ROUTING_MECHANISM and GATEWAY_SECURITY_PROTOCOL environment variables. This legacy network configuration is deprecated and will be removed in Gateway 3.23. New deployments should use listener configuration.
This page is for deployments still running on legacy network configuration. It documents how the deprecated mode behaves. To switch to listener configuration, see Migrate to listener configuration.
The legacy network configuration remains supported for now to give existing deployments time to migrate. Plan a migration; new functionality will not be backported to this mode.
Detect which mode you’re running
Gateway detects the configuration mode automatically at startup based on the environment variables you set:
| Mode | Trigger | Status |
|---|
| Explicit | Any GATEWAY_LISTENER_* env var is set | Recommended |
| Legacy network | Legacy env vars like GATEWAY_PORT_START are set | Deprecated, still supported |
| Zero-config | No listener or network env vars are set | Local development and testing only |
[main] [WARN] [SecurityParametersInference] - Legacy environment variables detected (GATEWAY_PORT_START, etc.). This configuration method is deprecated and will be removed in version 3.23. Please migrate to the new listener configuration format (GATEWAY_LISTENER_<NAME>_*): https://docs.conduktor.io/guide/tutorials/migrate-to-listener-configuration
[main] [INFO] [SecurityParametersInference] - Legacy config: securityMode=GATEWAY_MANAGED, aclEnabled=false
DEFAULT, so the Computed configuration block lists a DEFAULT listener in both legacy and listener configuration. The deprecation warning is what distinguishes the two.
How the legacy mode behaves
In legacy network configuration, Gateway infers missing security settings from the backing Kafka cluster.
Security mode and protocol inference
How Gateway determines default values for GATEWAY_SECURITY_PROTOCOL and GATEWAY_SECURITY_MODE depends on which of the two are explicitly set.
Both GATEWAY_SECURITY_PROTOCOL and GATEWAY_SECURITY_MODE unset: Gateway infers both from the Kafka cluster’s security protocol.
| Kafka cluster security protocol | Inferred GATEWAY_SECURITY_PROTOCOL | Inferred GATEWAY_SECURITY_MODE |
|---|
SASL_PLAINTEXT | SASL_PLAINTEXT | KAFKA_MANAGED |
SASL_SSL | SASL_SSL | KAFKA_MANAGED |
PLAINTEXT | PLAINTEXT | GATEWAY_MANAGED |
SSL | SSL | GATEWAY_MANAGED |
PLAINTEXT with GATEWAY_MANAGED mode.
Only GATEWAY_SECURITY_MODE set: Gateway infers the protocol from the combination.
GATEWAY_SECURITY_MODE | Kafka cluster security protocol | Inferred GATEWAY_SECURITY_PROTOCOL |
|---|
KAFKA_MANAGED | SASL_PLAINTEXT | SASL_PLAINTEXT |
KAFKA_MANAGED | SASL_SSL | SASL_SSL |
GATEWAY_MANAGED | PLAINTEXT | PLAINTEXT |
GATEWAY_MANAGED | SSL | SSL |
| Any other combination | | No default; Gateway requires manual setting |
GATEWAY_SECURITY_PROTOCOL set: Gateway infers the mode from the protocol.
GATEWAY_SECURITY_PROTOCOL | Inferred GATEWAY_SECURITY_MODE |
|---|
SASL_PLAINTEXT | GATEWAY_MANAGED |
SASL_SSL | GATEWAY_MANAGED |
PLAINTEXT | GATEWAY_MANAGED |
SSL | GATEWAY_MANAGED |
DELEGATED_SASL_PLAINTEXT (deprecated) | KAFKA_MANAGED |
DELEGATED_SASL_SSL (deprecated) | KAFKA_MANAGED |
The DELEGATED_SASL_PLAINTEXT and DELEGATED_SASL_SSL values were deprecated in Gateway 3.10.0 in favor of GATEWAY_SECURITY_MODE. They remain supported but are no longer recommended. See the security mode migration guide. ACL default
GATEWAY_ACL_ENABLED is inferred from the security mode:
GATEWAY_MANAGED → trueKAFKA_MANAGED → false
You can override the inferred value by setting GATEWAY_ACL_ENABLED explicitly.
Legacy environment variable reference
For reference, these are the environment variables that listener configuration replaces. Use them only on deployments that have not yet migrated.
| Environment variable | Description | Default |
|---|
| Common properties | | |
GATEWAY_ADVERTISED_HOST | The hostname returned in the Gateway’s metadata for clients to connect to. | Your hostname |
GATEWAY_ROUTING_MECHANISM | Defines the routing method: port for port routing, host for SNI routing. | port |
GATEWAY_PORT_START | The first port the Gateway listens on. | 6969 |
GATEWAY_BIND_HOST | The network interface the Gateway binds to. | 0.0.0.0 |
| Port routing specific | | |
GATEWAY_PORT_COUNT | The total number of ports used by Gateway. | (maxBrokerId - minBrokerId) + 3 |
| SNI routing specific | | |
GATEWAY_ADVERTISED_SNI_PORT | The port returned in the Gateway’s metadata when using SNI routing. | GATEWAY_PORT_START |
GATEWAY_ADVERTISED_HOST_PREFIX | Configures the advertised broker names. | broker |
GATEWAY_SNI_HOST_SEPARATOR | The separator used to construct returned metadata. | - |
GATEWAY_SECURITY_PROTOCOL | The security protocol clients use to connect to Gateway. Has to be SSL or SASL_SSL when in GATEWAY_MANAGED security mode, or SASL_SSL when in KAFKA_MANAGED security mode, for SNI routing. | Inferred from GATEWAY_SECURITY_MODE and KAFKA_SECURITY_PROTOCOL |
GATEWAY_SSL_CLIENT_AUTH | mTLS client authentication policy: NONE, OPTIONAL or REQUIRE. Replaced by the per-listener GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH. | NONE |
GATEWAY_MIN_BROKERID is unchanged and still applies to port routing under listener configuration. See Gateway environment variables.
