Skip to main content

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_MECHANISM and GATEWAY_SECURITY_PROTOCOL (full list)
  • The Helm chart’s gateway.portRange, or legacy variables in its gateway.env
This guide replaces them with per-listener 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 defaults GATEWAY_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.listeners by 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, set GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH on 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_MODE and GATEWAY_ACL_ENABLED, which you now have to set: see Set the security mode and ACL flag
  • GATEWAY_SSL_KEY_STORE_*
  • GATEWAY_SSL_TRUST_STORE_*
  • All KAFKA_* connection variables

Set the security mode and ACL flag

Listener configuration requires GATEWAY_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 is broker-{{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 your GATEWAY_ROUTING_MECHANISM. These examples use DEFAULT as the listener name.
This legacy network configuration:
Becomes:
What changed:
  • GATEWAY_PORT_START=9092 with GATEWAY_PORT_COUNT=6 maps to the port range 9092-9097.
  • GATEWAY_MIN_BROKERID is 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
  • The Computed configuration block lists each listener you defined, with the ports, advertised host, routing and security protocol you intended.
For the SNI worked example above, the block lists the DEFAULT listener:
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.

Kubernetes (Helm chart)

The Conduktor Gateway Helm chart translates gateway.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), replace gateway.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.
Becomes:
Port routing doesn’t need an external listener: all traffic goes through the internal service.

Helm values to listener variable mapping

The chart translates these values.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:
After upgrading, confirm the env vars and services are correct:
The same verification checks apply: confirm Gateway starts and the Computed configuration block lists your expected listeners.

Clean up

After confirming the new config works, remove these legacy keys from gateway.env in your values file:
  • GATEWAY_SECURITY_PROTOCOL
  • GATEWAY_ROUTING_MECHANISM
  • GATEWAY_ADVERTISED_HOST
  • GATEWAY_ADVERTISED_HOST_PREFIX
  • GATEWAY_SNI_HOST_SEPARATOR
  • GATEWAY_ADVERTISED_SNI_PORT
And remove gateway.portRange entirely, and gateway.preview.listeners: false if you set it.