Overview
Gateway 3.23.0 doesn’t start with legacy network configuration, which is any of:- The legacy global networking variables, such as
GATEWAY_PORT_*,GATEWAY_ROUTING_MECHANISMandGATEWAY_SECURITY_PROTOCOL(full list) - The Helm chart’s
gateway.portRange, or legacy variables in itsgateway.env
GATEWAY_LISTENER_<NAME>_* variables.
Choose your upgrade path
If you set no listener or networking variables, Gateway runs in zero-config mode and this migration doesn’t apply. From Gateway 3.19.0, zero-config mode defaultsGATEWAY_ACL_ENABLED to false. If you’re upgrading from an earlier version and rely on ACL checks, set GATEWAY_ACL_ENABLED=true.
Otherwise:
Switch once:
- At any point from 3.20.0, and no later than your upgrade to 3.23.0.
- With the Helm chart, when you first upgrade to chart 3.21.0 or later (Gateway 3.20.0). From that version, the chart uses
gateway.listenersby default. See Kubernetes (Helm chart).
Before you start
Check these before you plan the switch:- Security mode and ACL flag: listener configuration requires both, and legacy configuration worked them out for you. Find the values your deployment runs with today: a wrong ACL flag either denies every client or turns authorization off. See Set the security mode and ACL flag.
- SNI routing: the default advertised host pattern changes. If your DNS records and TLS certificates use the legacy names, update them or keep the legacy pattern: see SNI host patterns.
- mTLS: if you set
GATEWAY_SSL_CLIENT_AUTH, setGATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTHon every listener that should ask clients for a certificate. A listener without it doesn’t ask, so clients that authenticate with mTLS lose their identity.
Map legacy variables to listener variables
Legacy configuration runs a single listener. Replace it with one listener and give it a name, which goes in place of<NAME> in the variables below. The name has to start with a letter and contain only letters and digits, for example DEFAULT, the name legacy configuration used for its listener internally. The worked example uses it and shows a full configuration before and after.
Replace each legacy variable you set with its listener equivalent:
These variables stay global and keep their names:
GATEWAY_SECURITY_MODEandGATEWAY_ACL_ENABLED, which you now have to set: see Set the security mode and ACL flagGATEWAY_SSL_KEY_STORE_*GATEWAY_SSL_TRUST_STORE_*- All
KAFKA_*connection variables
Set the security mode and ACL flag
Listener configuration requiresGATEWAY_SECURITY_MODE and GATEWAY_ACL_ENABLED, and Gateway doesn’t start without them. Legacy network configuration worked them out from your other settings, so you may not have set them before.
If you already set GATEWAY_SECURITY_MODE, keep it. Otherwise, choose it from your legacy GATEWAY_SECURITY_PROTOCOL:
Then set
GATEWAY_ACL_ENABLED to the value your deployment runs with today, so the switch doesn’t change who’s authorized:
With
KAFKA_MANAGED, Gateway rejects true.
SNI host patterns
The default advertised host pattern isbroker-{{physicalCluster}}-{{nodeId}}.{{advertisedHost}}. This differs from the legacy default built from GATEWAY_ADVERTISED_HOST_PREFIX (default broker) and GATEWAY_SNI_HOST_SEPARATOR (default -). If your DNS records and TLS certificates match the legacy pattern, either update them or set the pattern explicitly to reproduce it:
Worked example
The migration depends on your routing mechanism. Pick the tab that matches yourGATEWAY_ROUTING_MECHANISM.
These examples use DEFAULT as the listener name.
- Port routing
- SNI routing
This legacy network configuration:Becomes:What changed:
GATEWAY_PORT_START=9092withGATEWAY_PORT_COUNT=6maps to the port range9092-9097.GATEWAY_MIN_BROKERIDis unchanged: it still maps ports to broker IDs in order under listener configuration.
Verify the migration
Restart Gateway and check the startup logs. Confirm that:- Gateway starts. If a legacy variable is still set, Gateway doesn’t start, and the error names every variable to unset. Search the logs for:
- 3.23.0 and later:
The following environment variables are no longer supported - 3.20.0 to 3.22.x:
Both listener-style configuration and legacy environment variables are present
- 3.23.0 and later:
- The
Computed configurationblock lists each listener you defined, with the ports, advertised host, routing and security protocol you intended.
DEFAULT listener:
-L) to confirm the metadata response advertises the expected hostnames and ports.
Kubernetes (Helm chart)
The Conduktor Gateway Helm chart translatesgateway.listeners.* values into GATEWAY_LISTENER_<NAME>_* environment variables.
The chart creates two listeners, each with its own ports, security protocol and routing mode: INTERNAL for cluster traffic, and EXTERNAL for client traffic, enabled with service.external.enable: true.
Upgrade from a chart version before 3.21.0
On your first upgrade to chart 3.21.0 or later (Gateway 3.20.0), replacegateway.portRange, which generates the legacy GATEWAY_PORT_START and GATEWAY_PORT_COUNT variables, with gateway.listeners. From that version, the chart uses gateway.listeners by default: see Helm chart compatibility. The migration depends on your routing mode.
- Port routing
- SNI routing
Helm values to listener variable mapping
The chart translates thesevalues.yaml paths into the listener env vars from the mapping table above:
Where
<name> is internal or external in values, mapped to INTERNAL or EXTERNAL in the env var.
Keystore handling with tls.enable
Any listener that uses SSL or SASL_SSL requires tls.enable: true (or tls.certManager.enabled: true), otherwise the chart fails validation. Setting GATEWAY_SSL_KEY_STORE_PATH through gateway.env alone doesn’t satisfy this: it works at runtime but not when the chart renders.
With tls.keystore.secretRef set, tls.enable: true generates these container env vars and mounts the secret at /etc/gateway/tls/:
These are explicit container env vars, so they override any same-named value from
gateway.env. If you mounted the keystore manually before, drop the manual GATEWAY_SSL_KEY_STORE_PATH and secret mount.
The keystore password is not generated unless tls.keystore.passwordSecretRef is set. Otherwise, keep supplying GATEWAY_SSL_KEY_STORE_PASSWORD through gateway.env or extraSecretEnvVars.
Verify the Helm upgrade
Preview the manifest changes before applying:Computed configuration block lists your expected listeners.
Clean up
After confirming the new config works, remove these legacy keys fromgateway.env in your values file:
GATEWAY_SECURITY_PROTOCOLGATEWAY_ROUTING_MECHANISMGATEWAY_ADVERTISED_HOSTGATEWAY_ADVERTISED_HOST_PREFIXGATEWAY_SNI_HOST_SEPARATORGATEWAY_ADVERTISED_SNI_PORT
gateway.portRange entirely, and gateway.preview.listeners: false if you set it.
Related resources
- Legacy network configuration: how the removed mode behaved and the full variable reference
- Configure Gateway listeners
- Configure Gateway listener security