Conduktor Gateway environment variables reference

To configure Conduktor Gateway, we recommend setting up environment variables. They can be set in the Gateway container or taken from a file. To make sure the values were set correctly, check the startup logs.

Use the Gateway container

Docker
Kubernetes

You can set the environment variables during the docker-run command with -e or --env:

docker run -d \
  -e KAFKA_BOOTSTRAP_SERVERS=kafka1:9092,kafka2:9092 \
  -e KAFKA_SECURITY_PROTOCOL=SASL_PLAINTEXT \
  -e KAFKA_SASL_MECHANISM=PLAIN \
  -e KAFKA_SASL_JAAS_CONFIG="org.apache.kafka.common.security.plain.PlainLoginModule required username='usr' password='pwd';" \
  -p 6969:6969 \
  conduktor/conduktor-gateway:latest

Or in a docker-compose.yaml:

services:
  conduktor-gateway:
    image: conduktor/conduktor-gateway:latest
    ports:
      - 6969:6969
    environment:
      KAFKA_BOOTSTRAP_SERVERS: kafka1:9092,kafka2:9092
      KAFKA_SECURITY_PROTOCOL: SASL_PLAINTEXT
      KAFKA_SASL_MECHANISM: PLAIN
      KAFKA_SASL_JAAS_CONFIG: org.apache.kafka.common.security.plain.PlainLoginModule required username='usr' password='pwd';

You can set the environment variables in the values.yaml of our Helm chart :

gateway:
  env:
    KAFKA_BOOTSTRAP_SERVERS: kafka1:9092,kafka2:9092
    KAFKA_SECURITY_PROTOCOL: SASL_PLAINTEXT
    KAFKA_SASL_MECHANISM: PLAIN
    KAFKA_SASL_JAAS_CONFIG: org.apache.kafka.common.security.plain.PlainLoginModule required username='usr' password='pwd';

Use a file

You can mount a file with the key-value pairs into the container and provide its path by setting the environment variable GATEWAY_ENV_FILE. Note these variables should be exported by the file as they are injected in the wrapper that starts the Gateway process.

Example

export KAFKA_BOOTSTRAP_SERVERS=kafka1:9092,kafka2:9092
export KAFKA_SECURITY_PROTOCOL=SASL_PLAINTEXT
export KAFKA_SASL_MECHANISM=PLAIN
export KAFKA_SASL_JAAS_CONFIG=org.apache.kafka.common.security.plain.PlainLoginModule required username='usr' password='pwd';

You’ll get a confirmation in the logs: Sourcing environment variables from $GATEWAY_ENV_FILE (or a warning if the file isn’t found: Warning: GATEWAY_ENV_FILE is set but the file does not exist or is not readable.).

Listeners

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.

Configure listeners using the pattern GATEWAY_LISTENER_<NAME>_<PROPERTY>, where <NAME> is a label you choose. See Configure Gateway listeners for details.

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.

Variable	Description	Default
`GATEWAY_LISTENER_<NAME>_ROUTING`	Routing mechanism: `port` or `sni`	Required
`GATEWAY_LISTENER_<NAME>_PORTS`	Port specification. See the format	Required
`GATEWAY_LISTENER_<NAME>_SECURITY_PROTOCOL`	Security protocol: `PLAINTEXT`, `SSL`, `SASL_SSL`, or `SASL_PLAINTEXT`	Required
`GATEWAY_LISTENER_<NAME>_BIND_ADDRESS`	Network interface to bind to	`0.0.0.0`
`GATEWAY_LISTENER_<NAME>_ADVERTISED_HOST`	Hostname returned to clients	System hostname or `localhost`
`GATEWAY_LISTENER_<NAME>_ADVERTISED_HOST_PATTERN`	Template for per-broker hostnames. Only used when routing is set to `sni`.	`broker-{{physicalCluster}}-{{nodeId}}.{{advertisedHost}}`
`GATEWAY_LISTENER_<NAME>_BOOTSTRAP_HOST_PATTERN`	Template for bootstrap hostname. Only used when routing is set to `sni`.	Derived from `ADVERTISED_HOST_PATTERN`, or `bootstrap-{{physicalCluster}}.{{advertisedHost}}` if not set
`GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH`	mTLS client authentication policy: `NONE`, `OPTIONAL`, or `REQUIRE`. See the modes	`NONE`

The following global variable applies to all listeners that use port routing:

Variable	Description	Default
`GATEWAY_MIN_BROKERID`	The broker ID mapped to the first port. Set it to the lowest `broker.id` (or `node.id`) in the backing Kafka cluster.	`0`

Listeners: port specification format

GATEWAY_LISTENER_<NAME>_PORTS accepts ranges, individual values, or a combination of both, separated by commas:

GATEWAY_LISTENER_EXTERNAL_PORTS=9092-9095
GATEWAY_LISTENER_EXTERNAL_PORTS=9092,9093,9094,9095
GATEWAY_LISTENER_EXTERNAL_PORTS=9092-9093,9100,9200

When the advertised ports differ from the local ports (for example, behind a NAT or in Docker), use the advertised:local format:

GATEWAY_LISTENER_EXTERNAL_PORTS=29092-29095:9092-9095

You can mix ranges and individual ports with local mappings. For example, with GATEWAY_MIN_BROKERID=0 and three brokers:

# Broker 0 → advertised 29092, local 9092
# Broker 1 → advertised 29093, local 9093
# Broker 2 → advertised 29100, local 9100
GATEWAY_LISTENER_EXTERNAL_PORTS=29092-29093:9092-9093,29100:9100

For SNI routing, the listener uses a single port; the advertised:local format maps the advertised port (for example, a load balancer’s 443) to the local one:

GATEWAY_LISTENER_EXTERNAL_PORTS=443:9192

Listeners: SSL client authentication modes

The GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH setting controls whether the Gateway requests a client certificate during the TLS handshake for a specific listener:

Mode	Behavior
`NONE`	No client certificate is requested. This is standard one-way TLS where only the server is authenticated.
`OPTIONAL`	The Gateway requests a client certificate but allows the connection if the client does not provide one. Useful when some clients support mTLS and others do not.
`REQUIRE`	The Gateway requires a valid client certificate. Connections without a certificate are rejected during the TLS handshake.

When SSL_CLIENT_AUTH is set to OPTIONAL or REQUIRE, you must configure a truststore in sslConfig.trustStore containing the CA certificates used to verify client certificates.

Listeners: zero-config mode

If you don’t set any listener or networking environment variables, Gateway configures itself automatically. It creates a single listener named DEFAULT with port routing, assigning ports from 6969 (one per broker, plus two for headroom), and takes the listener’s security protocol from the backing Kafka cluster. GATEWAY_ACL_ENABLED defaults to false in this mode. When GATEWAY_SECURITY_MODE is not set, Gateway infers it from the backing cluster’s security protocol:

Backing Kafka security protocol	Inferred `GATEWAY_SECURITY_MODE`
`SASL_PLAINTEXT`, `SASL_SSL`	`KAFKA_MANAGED`
`PLAINTEXT`, `SSL`	`GATEWAY_MANAGED`

Zero-config mode is for local development and testing only. Configure your listeners, security mode and ACLs explicitly for production deployments.

Listeners: legacy configuration (deprecated)

These global variables are deprecated in favor of per-listener configuration. They remain supported for now. For how they behave, see Legacy network configuration; to switch, see Migrate to listener configuration.

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`

Load balancing

Environment variable	Description	Default value
`GATEWAY_FEATURE_FLAGS_INTERNAL_LOAD_BALANCING`	Whether to use Conduktor Gateway’s internal load balancer to balance connections between Gateway instances.	`true`
`GATEWAY_CLUSTER_ID`	A unique identifier for a given Gateway cluster, used to establish Gateway cluster membership for load balancing.	`gateway`
`GATEWAY_GROUP_ID`	Consumer group name used by Gateways in the same cluster to recognize each other.	`conduktor_${GATEWAY_CLUSTER_ID}`
`GATEWAY_RACK_ID`	Similar to `broker.rack`.

Connect Gateway to Kafka

Conduktor Gateway’s connection to Kafka is configured by the KAFKA_ environment variables. When translating Kafka’s properties, use upper case instead and replace the . with _. For example: When defining Gateway’s Kafka property bootstrap.servers, declare it as the environment variable KAFKA_BOOTSTRAP_SERVERS. Any variable prefixed with KAFKA_ will be treated as a connection parameter by Gateway.

Connection pooling

Environment variable	Description	Default value
`GATEWAY_UPSTREAM_CONNECTION_POOL_TYPE`	Upstream connection pool type. Possible values are `NONE` (no connection pool), `ROUND_ROBIN` (Round robin selected connection pool)	`NONE`
`GATEWAY_UPSTREAM_NUM_CONNECTION`	The number of connections between Conduktor Gateway and Kafka per upstream thread. Used only when `ROUND_ROBIN` is enabled.	`10`

Cluster switch failover

Setting up your Kafka clusters for failover is similar to the standard setup, but you need to provide two sets of properties: one for your main cluster and one for your failover cluster. You can define these properties as environment variables or load a cluster configuration file.

Environment variable	Description
`GATEWAY_BACKEND_KAFKA_SELECTOR`	Indicates the use of a configuration file and provides its path, e.g.: `'file: { path: /cluster-config.yaml }'`.
`KAFKA_FAILOVER_GATEWAY_ROLES`	To turn Gateway into failover mode, set this to `failover`.
Main Cluster
`KAFKA_MAIN_BOOTSTRAP_SERVERS`	Bootstrap server.
`KAFKA_MAIN_SECURITY_PROTOCOL`	Security protocol.
`KAFKA_MAIN_SASL_MECHANISM`	SASL mechanism.
`KAFKA_MAIN_SASL_JAAS_CONFIG`	SASL JAAS config.
Failover Cluster
`KAFKA_FAILOVER_BOOTSTRAP_SERVERS`	Bootstrap server.
`KAFKA_FAILOVER_SECURITY_PROTOCOL`	Security protocol.
`KAFKA_FAILOVER_SASL_MECHANISM`	SASL mechanism.
`KAFKA_FAILOVER_SASL_JAAS_CONFIG`	SASL JAAS config.

Security and authentication

These global settings determine where authentication and authorization take place, and how clients authenticate. The security protocol itself is set per listener — see Listeners.

Environment variable	Description	Default value
`GATEWAY_SECURITY_MODE`	Define where authentication takes place, Gateway or Kafka. Valid values are: `GATEWAY_MANAGED`, `KAFKA_MANAGED`. Note that `KAFKA_MANAGED` mode is incompatible with `PLAINTEXT` or `SSL` security protocols.	Required (set explicitly). For inference with legacy network configuration, see Legacy network configuration.
`GATEWAY_ACL_ENABLED`	Enable/disable ACL support on the Gateway transparent virtual cluster (`passthrough`) only.	Required (set explicitly). For inference with legacy network configuration, see Legacy network configuration.
`GATEWAY_SUPER_USERS`	Semicolon-separated (`;`) list of service accounts that will be super users on Gateway (excluding virtual clusters). Example: `alice;bob`.	Usernames from GATEWAY_ADMIN_API_USERS
`GATEWAY_FEATURE_FLAGS_MANDATORY_VCLUSTER`	If no virtual cluster was detected, the user then automatically falls back into the transparent virtual cluster called `passthrough`. If set to true, reject authentication if the principal (the identifier the authentication process provides) is not mapped to a named virtual cluster with a service account. This must be set to true when using the Partner Zones feature.	`false`
`GATEWAY_AUTHENTICATION_CONNECTION_MAX_REAUTH_MS`	Force the client re-authentication after this amount of time. If set to 0, we never force the client to re-authenticate until the next connection	`0`
`GATEWAY_ACL_STORE_ENABLED`	Obsolete, use the VirtualCluster resource. Enable/disable ACLs support for Virtual Clusters only.	`false`
`GATEWAY_USER_POOL_SERVICE_ACCOUNT_REQUIRED`	Obsolete Verified the existence of user mapping for the service account when the user connects in Gateway Managed SASL/PLAIN mode. As of Gateway v3.9.0, this variable no longer exists: the behavior is always on.

Set the security protocol clients use to connect to Gateway per listener, with GATEWAY_LISTENER_<NAME>_SECURITY_PROTOCOL (see Listeners). The global GATEWAY_SECURITY_PROTOCOL and its deprecated DELEGATED_* values apply only to legacy network configuration.

SSL authentication

Environment variable	Description	Default value
Keystore
`GATEWAY_SSL_KEY_STORE_PATH`	Path to a mounted keystore for SSL connections
`GATEWAY_SSL_KEY_STORE_PASSWORD`	Password for the keystore defined above
`GATEWAY_SSL_KEY_PASSWORD`	Password for the key contained in the store above
`GATEWAY_SSL_KEY_TYPE`	`jks`or `pkcs12`	`jks`
`GATEWAY_SSL_UPDATE_CONTEXT_INTERVAL_MINUTES`	Interval in minutes to refresh SSL context	`5`
Truststore (for mTLS)
`GATEWAY_SSL_TRUST_STORE_PATH`	Path to a keystore for SSL connections
`GATEWAY_SSL_TRUST_STORE_PASSWORD`	Password for the truststore defined above
`GATEWAY_SSL_TRUST_STORE_TYPE`	`jks`, `pkcs12`	`jks`
`GATEWAY_SSL_PRINCIPAL_MAPPING_RULES`	mTLS leverages SSL mutual authentication to identify a Kafka client. Principal for mTLS connection can be detected from the subject certificate using the same feature as in Apache Kafka, the SSL principal mapping	Extracts the subject
`GATEWAY_SSL_ENABLED_PROTOCOLS`	Comma-separated list of TLS protocol versions; restricts which protocols are offered during SSL/TLS handshake. If not provided it will fall back to the default protocols of security provider configured by `GATEWAY_SECURITY_PROVIDER`.
`GATEWAY_SSL_CIPHER_SUITES`	Comma-separated list of cipher suites; restricts cryptographic algorithms that are offered during SSL/TLS handshake. If not provided it will fall back to the default ciphers of security provider configured by `GATEWAY_SECURITY_PROVIDER`.

The keystore and truststore are shared across all listeners. mTLS client authentication is set per listener with GATEWAY_LISTENER_<NAME>_SSL_CLIENT_AUTH — the global GATEWAY_SSL_CLIENT_AUTH applies only to legacy network configuration.

Password values (GATEWAY_SSL_KEY_STORE_PASSWORD, GATEWAY_SSL_KEY_PASSWORD, GATEWAY_SSL_TRUST_STORE_PASSWORD) support any characters except a literal single-quote ('). Pattern: [^']*

OAuthbearer

Some of these definitions (e.g. SASL_OAUTHBEARER_JWKS_ENDPOINT_REFRESH) are taken from Kafka documentation .

Environment variable	Description
`GATEWAY_OAUTH_JWKS_URL`	The OAuth/OIDC provider URL from which the provider’s JWKS (JSON Web Key Set) can be retrieved. The URL can be HTTP(S)-based or file-based.
`GATEWAY_OAUTH_EXPECTED_ISSUER`	The (optional) setting for the broker to use to verify that the JWT was created by the expected issuer. The JWT will be inspected for the standard OAuth `iss` claim and if this value is set, the broker will match it exactly against what is in the JWT’s `iss` claim. If there’s no match, the broker will reject the JWT and authentication will fail
`GATEWAY_OAUTH_EXPECTED_AUDIENCES`	The (optional) comma-delimited setting for the broker to use to verify that the JWT was issued for one of the expected audiences. The JWT will be inspected for the standard OAuth `aud` claim and if this value is set, the broker will match the value from JWT’s `aud` claim to see if there is an exact match. If there’s no match, the broker will reject the JWT and authentication will fail.
`GATEWAY_OAUTH_JWKS_REFRESH`	The (optional) value in milliseconds for the broker to wait between refreshing its JWKS (JSON Web Key Set) cache that contains the keys to verify the signature of the JWT.
`GATEWAY_OAUTH_JWKS_RETRY`	The (optional) value in milliseconds for the initial wait between JWKS (JSON Web Key Set) retrieval attempts from the external authentication provider. JWKS retrieval uses an exponential backoff algorithm with an initial wait based on the sasl.oauthbearer.jwks.endpoint.retry.backoff.ms setting and will double in wait length between attempts, up to a maximum wait length specified by sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms.
`GATEWAY_OAUTH_JWKS_MAX_RETRY`	The (optional) value in milliseconds for the maximum wait between attempts to retrieve the JWKS (JSON Web Key Set) from the external authentication provider. JWKS retrieval uses an exponential backoff algorithm with an initial wait based on the sasl.oauthbearer.jwks.endpoint.retry.backoff.ms setting and will double in wait length between attempts, up to a maximum wait length specified by sasl.oauthbearer.jwks.endpoint.retry.backoff.max.ms.
`GATEWAY_OAUTH_SCOPE_CLAIM_NAME`	The OAuth claim for the scope is often named `scope` but this (optional) setting can provide a different name to use for the scope included in the JWT payload’s claims, if the OAuth/OIDC provider uses a different name for that claim.
`GATEWAY_OAUTH_SUB_CLAIM_NAME`	The OAuth claim for the subject is often named `sub`, but this (optional) setting can provide a different name to use for the subject included in the JWT payload’s claims, if the OAuth/OIDC provider uses a different name for that claim.
`GATEWAY_OAUTH_USE_CC_POOL_ID`	Set to `true` to use the Confluent Cloud pool ID as the principal name. This is useful for Confluent Cloud users in Delegated mode who want to use the pool ID as the principal name instead of the `sub` claim.

Principal resolver

Environment variable	Description	Default value
`GATEWAY_PRINCIPAL_RESOLVER`	The principal resolver to use. Currently only supported is `CONFLUENT_CLOUD`.
`GATEWAY_CONFLUENT_CLOUD_API_KEY`	The Confluent Cloud API key (not the Kafka cluster API key).
`GATEWAY_CONFLUENT_CLOUD_API_SECRET`	The Confluent Cloud API secret.
`GATEWAY_CONFLUENT_CLOUD_CACHE_SIZE`	The number of principals to cache.	`1000`
`GATEWAY_CONFLUENT_CLOUD_CACHE_EXPIRY_MS`	The cache expiry time in milliseconds.	`86400000` (1 day)

Find out more about the principal resolver.

Plain authentication

Environment variable	Description	Default value
`GATEWAY_USER_POOL_SECRET_KEY`	Base64 encoded value of 256bits long (e.g. `openssl rand -base64 32`). If using SASL_PLAIN or SASL_SSL, you have the ability to create local service accounts on Gateway. These service accounts will have credentials generated by Gateway based on the `GATEWAY_USER_POOL_SECRET_KEY`.	No default value is provided. You must provide this value for all deployments

Security provider

Environment variable	Description	Default value
`GATEWAY_SECURITY_PROVIDER`	Specify your security provider. It can be: `DEFAULT` (from your JRE), `BOUNCY_CASTLE`, `BOUNCY_CASTLE_FIPS` and `CONSCRYPT`. Please note that `CONSCRYPT` doesn’t support Mac OS with aarch64.	`DEFAULT`

HTTP API

Environment variable	Description	Default value
`GATEWAY_HTTP_PORT`	The port on which Gateway will present the HTTP management API.	`8888`
`GATEWAY_SECURED_METRICS`	Determines whether the HTTP management API requires authentication.	`true`
`GATEWAY_ADMIN_API_USERS`	Users that can access the API. Set `admin: true` for full access (required for write operations). Set `admin: false` (default) for read-only access.	`[{username: admin, password: conduktor, admin: true}]`
HTTPS configuration
`GATEWAY_HTTPS_KEY_STORE_PATH`	Enables HTTPS and specifies the keystore to use for TLS connections.
`GATEWAY_HTTPS_KEY_STORE_PASSWORD`	Sets the password for the keystore used in HTTPS TLS connections.
`GATEWAY_HTTPS_CLIENT_AUTH`	Client authentication configuration for mTLS. Possible values: `NONE`, `REQUEST`, `REQUIRED`.	`NONE`
`GATEWAY_HTTPS_TRUST_STORE_PATH`	Specifies the truststore used for mTLS.
`GATEWAY_HTTPS_TRUST_STORE_PASSWORD`	Password for the truststore defined above.

Password values (GATEWAY_HTTPS_KEY_STORE_PASSWORD, GATEWAY_HTTPS_TRUST_STORE_PASSWORD) support any characters except a literal single-quote ('). Pattern: [^']*

Feature flags

Environment variable	Description	Default value
`GATEWAY_FEATURE_FLAGS_AUDIT`	Whether or not to enable the audit feature.	`true`
`GATEWAY_FEATURE_FLAGS_INTERNAL_LOAD_BALANCING`	Whether or not to enable Gateway’s internal load balancing.	`true`
`GATEWAY_FEATURE_FLAGS_BLOCK_UNSUPPORTED_APIS`	Whether to block Kafka APIs that aren’t explicitly supported by Gateway. See API blocking modes.	`false`
`GATEWAY_FEATURE_FLAGS_TEST_TOKENIZATION`	Whether to enable the `test-tokenization://` KMS in the encryption plugin family. Find out more about KMS integration.	`false`
`GATEWAY_FEATURE_FLAGS_HAPROXY_PROTOCOL`	Whether to enable HAProxy protocol support. Find out more about HAProxy Protocol.	`false`
`GATEWAY_FEATURE_FLAGS_TOPIC_ID_SUPPORT`	Whether to enable topic-ID based Kafka protocol handling (preview). See topic ID support.	`false`
`GATEWAY_FEATURE_FLAGS_INCREMENTAL_FETCH_SESSIONS_ENABLED`	Whether to support Apache Kafka incremental fetch sessions (KIP-227) on the Fetch API (preview). You can’t enable this at the same time as `GATEWAY_FEATURE_FLAGS_TOPIC_ID_SUPPORT`. See incremental fetch sessions.	`false`
`GATEWAY_AUTO_CREATE_TOPICS_ENABLED`	Enable auto-create topics feature. When enabled, topics can be automatically created when producing or consuming through Gateway, leveraging the Kafka property auto.create.topics.enable. Authorization: When enabled, users require either `CLUSTER` resource with `CREATE` permission (allows creating any topic) or `TOPIC` resource with `CREATE` permission for specific topics. Warning: this feature doesn’t support concentrated topics. When auto-create topics is enabled, topics that would normally be concentrated not be, they’ll simply be created as regular physical topics instead. Take caution when enabling this setting.	`false`

Topic ID support (preview)

Gateway supports topic-ID based Kafka protocol handling. Initial coverage is limited to the Fetch API: when disabled (default), Gateway advertises Fetch up to v12 during ApiVersions negotiation to force topic-name fetches; when enabled, clients can negotiate Fetch v13 or higher. Additional APIs will land behind the same flag in upcoming releases. Enable by setting GATEWAY_FEATURE_FLAGS_TOPIC_ID_SUPPORT=true. You can’t enable it at the same time as incremental fetch sessions — Gateway doesn’t start when both flags are set.

This is a preview feature. We recommend enabling it only in non-production environments.

Incremental fetch sessions (preview)

Apache Kafka clients can use incremental fetch sessions (KIP-227) to make Fetch requests smaller: a consumer opens a session with a first, full Fetch request, then sends only the partitions that changed on each later request while the broker tracks the rest. When you enable this flag, Gateway supports these sessions through the proxy. Enable by setting GATEWAY_FEATURE_FLAGS_INCREMENTAL_FETCH_SESSIONS_ENABLED=true.

This is a preview feature. We recommend enabling it only in non-production environments.

Incompatibilities

Topic ID support: you can’t combine incremental fetch sessions with topic ID support. Gateway doesn’t start when both GATEWAY_FEATURE_FLAGS_INCREMENTAL_FETCH_SESSIONS_ENABLED and GATEWAY_FEATURE_FLAGS_TOPIC_ID_SUPPORT are set to true. Disable one of them.
SQL and CEL topics: these deprecated logical topics are incompatible with incremental fetch sessions and return incorrect results when it’s enabled. Topic views aren’t affected.

If you use the audit Interceptor or a fetch policy, enabling incremental fetch sessions changes how they behave. See those pages for details.

Licensing

Environment variable	Description	Default value
`GATEWAY_LICENSE_KEY`	License key (required)

Monitoring

Audit

Environment variable	Description	Default value
`GATEWAY_AUDIT_LOG_CONFIG_SPEC_VERSION`	Version of the log.	`0.1.0`
`GATEWAY_AUDIT_LOG_SERVICE_BACKING_TOPIC`	Target topic name.	`_auditLogs`
`GATEWAY_AUDIT_LOG_REPLICATION_FACTOR_OF_TOPIC`	Replication factor to be used when creating the audit topic, defaults to the one defined in your cluster settings.	`-1`
`GATEWAY_AUDIT_LOG_NUM_PARTITIONS_OF_TOPIC`	Number of partitions to be used when creating the audit topic, defaults to the one defined in your cluster settings.	`-1`
`GATEWAY_AUDIT_LOG_KAFKA_`	Overrides Kafka Producer configuration for audit logs, i.e.: `GATEWAY_AUDIT_LOG_KAFKA_LINGER_MS=0`
`GATEWAY_AUDIT_LOG_EVENT_TYPES`	Comma-separated list of event types for audit log, defaults to `ALL` to generate audit log for all event types.	`ALL`

GATEWAY_AUDIT_LOG_EVENT_TYPES valid value is ALL (default) or a comma-separated list of the following:

CONNECTION for initial connection event, i.e. receiving Kafka’s API_VERSIONS request
AUTHENTICATION for authentication success or failure event
REST_API for all REST v1 admin requests and all REST v2 requests (see API reference)
ACL_ADMIN for ACL management events done via Kafka Admin API, i.e. CREATE_ACLS and DELETE_ACLS requests
AUTHORIZATION for authorization failure events, i.e. when ACL permissions deny an operation on a resource

Find out more about Gateway audit event types, including Kafka API key auditing.

Logging

Environment variable	Description	Default value	Package
`LOG4J2_APPENDER_LAYOUT`	The format to output Console logging. Use `json` for json layout or `pattern` for pattern layout.	`pattern`
`LOG4J2_TIME_FORMAT`	Timestamp format in log output.	`yyyy-MM-dd'T'HH:mm:ss.SSSZ`
`LOG4J2_IO_CONDUKTOR_PROXY_NETWORK_LEVEL`	Low-level networking, connection mapping, authentication, authorization.	`info`	io.conduktor.proxy.network
`LOG4J2_IO_CONDUKTOR_UPSTREAM_THREAD_LEVEL`	Requests processing and forwarding. At `trace`, log requests sent.	`warn`	io.conduktor.proxy.thread.UpstreamThread
`LOG4J2_IO_CONDUKTOR_PROXY_REBUILDER_COMPONENTS_LEVEL`	Requests and responses rewriting. Logs responses payload in `debug` (useful for checking METADATA).	`info`	io.conduktor.proxy.rebuilder.components
`LOG4J2_IO_CONDUKTOR_PROXY_SERVICE_LEVEL`	Various. Logs ACL checks and Interceptor targeting at `debug`. Logs post-interceptor requests/response payload at `trace`.	`info`	io.conduktor.proxy.service
`LOG4J2_IO_CONDUKTOR_PROXY_AUTHORIZATION_LEVEL`	Authorization decision logs.	`info`	io.conduktor.proxy.authorization
`LOG4J2_IO_CONDUKTOR_LEVEL`	Get even more logs not covered by specific packages.	`info`	io.conduktor
`LOG4J2_ORG_APACHE_KAFKA_LEVEL`	Kafka log level.	`warn`	org.apache.kafka
`LOG4J2_IO_KCACHE_LEVEL`	Kcache log level (our persistence library).	`warn`	io.kcache
`LOG4J2_IO_VERTX_LEVEL`	Vertx log level (our HTTP API framework).	`warn`	io.vertx
`LOG4J2_IO_NETTY_LEVEL`	Netty log level (our network framework).	`error`	io.netty
`LOG4J2_IO_MICROMETER_LEVEL`	Micrometer log level (our metrics framework).	`error`	io.micrometer
`LOG4J2_IO_CONFLUENT_LEVEL`	Confluent library logs.	`warn`	io.confluent
`LOG4J2_COM_FORTANIX_LEVEL`	Fortanix SDK logs (suppressed by default).	`off`	com.fortanix
`LOG4J2_ROOT_LEVEL`	Root logging level (applies to anything else that hasn’t been listed above).	`info`	(root)

Product analytics

Environment variable	Description	Default value
`GATEWAY_FEATURE_FLAGS_ANALYTICS`	Conduktor collects basic user analytics to understand product usage and enhance product development and improvement, such as a Gateway Started event. This is not based on any of the underlying Kafka data which is never sent to Conduktor.	`true`

Advanced configuration

These settings are for advanced tuning and debugging. Most deployments don’t need to change them.

Threading

Environment variable	Description	Default value
`GATEWAY_DOWNSTREAM_THREAD`	The number of threads dedicated to handling IO between clients and Conduktor Gateway.	Number of cores
`GATEWAY_UPSTREAM_THREAD`	The number of threads dedicated to handling IO between Kafka and Conduktor Gateway.	Number of cores

Gateway internal timeout

These timeout thresholds are used by Gateway and typically don’t need modification since they match Apache Kafka’s defaults. If your Kafka brokers or clients use non-default timeout values, you may want to adjust these.

Environment variable	Description	Default value
`GATEWAY_INFLIGHT_REQUEST_EXPIRY_MS`	Timeout for in-flight requests. If Kafka doesn’t respond before this delay, Gateway will respond with a request timeout to the client. Default is `300000`. It has to exceed the consumer’s `max.poll.interval.ms` and client’s `request.timeout.ms` because JOIN_GROUP or SYNC_GROUP requests can take up to that duration per KIP-62.	`330000`
`GATEWAY_UPSTREAM_MAX_IDLE_TIME_MS`	Maximum time Gateway connections can remain idle before being closed, in milliseconds. Default is `600000`. It has to exceed the Kafka broker’s `connections.max.idle.ms` and should be set higher than `GATEWAY_INFLIGHT_REQUEST_EXPIRY_MS`.	`660000`

Graceful shutdown

Environment variable	Description	Default value
`GATEWAY_SHUTDOWN_DELAY_BETWEEN_BROKERS_MS`	The pause between disconnection of broker clients during shutdown process. Set to `1000` or higher for librdkafka clients.	`0`

During shutdown, Gateway closes client connections in controlled manner to simulate rolling Kafka broker restart, with GATEWAY_SHUTDOWN_DELAY_BETWEEN_BROKERS_MS pause between brokers. For librdkafka clients, set GATEWAY_SHUTDOWN_DELAY_BETWEEN_BROKERS_MS to 1000 or higher to prevent them from crashing during shutdown because of ALL_BROKERS_DOWN error.

Internal topics

As Gateway is stateless, it uses Kafka topics to store its internal state. Use the following environment variables to configure these internal topics. If missing, Gateway will automatically create the topics (if it has the permission to do so). You can also create the topics independently of Gateway, just make sure they are configured as described below.

Internal state

Firstly, there are some general configuration settings for Gateway internal state management which apply to all used topics.

Environment variable	Description	Default value
`GATEWAY_STORE_TTL_MS`	Time between full refresh.	`604800000`
`GATEWAY_TOPIC_STORE_KCACHE_REPLICATION_FACTOR`	Defaults to the value defined in your cluster settings.	`-1`

Topic names

Environment variable	Description	Default value
`GATEWAY_TOPIC_MAPPINGS_TOPIC`	Topic where the topics aliases are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_topicmappings`
`GATEWAY_USER_MAPPINGS_TOPIC`	Topic where the service accounts are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_usermappings`
`GATEWAY_CONSUMER_OFFSETS_TOPIC`	Topic where the offsets for concentrated topic consumption are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_consumer_offsets`
`GATEWAY_INTERCEPTOR_CONFIGS_TOPIC`	Topic where the deployed Interceptors are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_interceptor_configs`
`GATEWAY_ACLS_TOPIC`	Topic where the ACLs managed by Gateway are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_acls`
`GATEWAY_AUDIT_LOG_TOPIC`	Topic where Gateway audit log is stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_auditlogs`
`GATEWAY_VCLUSTERS_TOPIC`	Topic where the virtual clusters are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_vclusters`
`GATEWAY_GROUPS_TOPIC`	Topic where the service account groups are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_groups`
`GATEWAY_ENCRYPTION_KEYS_TOPIC`	Name of the topic for storing EDEKs when `gateway` KMS enabled in encryption Interceptors	`_conduktor_${GATEWAY_CLUSTER_ID}_encryption_keys`
`GATEWAY_DATA_QUALITY_TOPIC`	Topic where the data quality violation are stored.	`_conduktor_${GATEWAY_CLUSTER_ID}_data_quality_violation`

Required topic configuration

The most important setting is log.cleanup.policy which defines the clean up policy for the topic. Most of the topics used by Gateway are compacted, but some use time-based retention. If this isn’t set up properly, Gateway will throw an error on startup. Set the following:

log.cleanup.policy=compact for compaction
log.cleanup.policy=delete for time based retention

If Gateway creates the topics for you, it will set the right values. The second vital setting is the replication factor. This should be set to at least 3 in production environments to ensure that the data is safe (Gateway will warn you on startup, if it’s set to less than three). When creating topics, Gateway uses the default value for your Kafka brokers for this setting. For partition count, most of the topics are low volume and can operate well with only a single partition. This isn’t enforced (Gateway will work with multi partition topics for internal state), however there is no need to have more than one partition. The exception to this is the audit log topic which can have a lot of events written to it, if enabled for a busy cluster. We recommend starting with 3 partitions for audit logs (this doesn’t affect Gateway performance as it is a writer, not a reader), but will impact any other consumers you may run reading from it.

Topic	Cleanup policy	Recommended partitions	Other configuration
`_conduktor_${GATEWAY_CLUSTER_ID}_topicmappings`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_usermappings`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_consumer_offsets`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_interceptor_configs`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_acls`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_vclusters`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_groups`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_encryption_keys`	compact	1
`_conduktor_${GATEWAY_CLUSTER_ID}_auditlogs`	delete	3	We recommend a retention time of around 7 days for this topic due to its high volume.
`_conduktor_${GATEWAY_CLUSTER_ID}_data_quality_violation`	delete	1

Data Quality topic configs

Environment variable	Description	Default value
`GATEWAY_DATA_QUALITY_TOPIC`	Target topic name	`_conduktor_${GATEWAY_CLUSTER_ID}_data_quality_violation`
`GATEWAY_DATA_QUALITY_TOPIC_REPLICATION_FACTOR`	Replication factor to be used when creating the data quality topic, defaults to the one defined in your cluster settings	cluster default
`GATEWAY_DATA_QUALITY_TOPIC_PARTITIONS`	Number of partitions to be used when creating the data quality topic, defaults to the one defined in your cluster settings	cluster default
`GATEWAY_DATA_QUALITY_TOPIC_RETENTION_HOUR`	Retention period (in hours) to be used when creating the data quality topic	168 (7 days)

API blocking modes

The GATEWAY_FEATURE_FLAGS_BLOCK_UNSUPPORTED_APIS environment variable controls how Gateway handles Kafka APIs that aren’t explicitly supported. Two modes:

Permissive mode (false, default): Gateway allows unsupported APIs to pass through - maintains backward compatibility
Restrictive mode (true): Gateway blocks unsupported APIs for enhanced security

When to use each:

Use permissive (default) when upgrading or if you have legacy applications
Use restrictive when you want maximum security and only allow known, supported APIs

Impact of each mode: Permissive mode (false):

✅ Backward compatibility: Legacy applications continue to work
✅ Smooth upgrades: No breaking changes during Gateway updates
⚠️ Security risk: Unsupported APIs bypass Gateway’s security controls

Restrictive mode (true):

✅ Enhanced security: Only explicitly supported APIs are allowed
✅ Controlled environment: Prevents access to potentially problematic APIs
❌ Breaking changes: Applications using unsupported APIs will fail

APIs not supported by Gateway: Gateway categorizes unsupported APIs into two groups:

Stability-blocked APIs (always blocked):

Stability (APIs not yet fully implemented or tested in Gateway):
DESCRIBE_TOPIC_PARTITIONS - New API for describing topic partitions
CONSUMER_GROUP_DESCRIBE - New consumer group protocol API (KIP-848)
CONSUMER_GROUP_HEARTBEAT - New consumer group protocol API (KIP-848)
New Kafka 4 group protocols (Gateway has no rebuilder for these, so it blocks them for every client):
Share groups (KIP-932), also known as Kafka queues: SHARE_GROUP_HEARTBEAT, SHARE_GROUP_DESCRIBE, SHARE_FETCH, SHARE_ACKNOWLEDGE, INITIALIZE_SHARE_GROUP_STATE, READ_SHARE_GROUP_STATE, WRITE_SHARE_GROUP_STATE, DELETE_SHARE_GROUP_STATE, READ_SHARE_GROUP_STATE_SUMMARY, DESCRIBE_SHARE_GROUP_OFFSETS, ALTER_SHARE_GROUP_OFFSETS, DELETE_SHARE_GROUP_OFFSETS
Streams groups (KIP-1071), the new Kafka Streams rebalance protocol: STREAMS_GROUP_HEARTBEAT, STREAMS_GROUP_DESCRIBE
Admin operations (these operations should be performed directly on the underlying Kafka cluster rather than through Gateway):
ALTER_REPLICA_LOG_DIRS - Admin operation for altering replica log directories
ELECT_LEADERS - Admin operation for leader election
ALTER_PARTITION_REASSIGNMENTS - Admin operation for partition reassignments
LIST_PARTITION_REASSIGNMENTS - Admin operation for listing partition reassignments
ALTER_PARTITION - Admin operation for altering partitions
ALLOCATE_PRODUCER_IDS - Admin operation for producer ID allocation
CREATE_DELEGATION_TOKEN - Admin operation for creating delegation tokens
RENEW_DELEGATION_TOKEN - Admin operation for renewing delegation tokens
EXPIRE_DELEGATION_TOKEN - Admin operation for expiring delegation tokens
DESCRIBE_DELEGATION_TOKEN - Admin operation for describing delegation tokens
DESCRIBE_USER_SCRAM_CREDENTIALS - Admin operation for describing SCRAM credentials
ALTER_USER_SCRAM_CREDENTIALS - Admin operation for altering SCRAM credentials
DESCRIBE_CLIENT_QUOTAS - Admin operation for describing client quotas
ALTER_CLIENT_QUOTAS - Admin operation for altering client quotas
UPDATE_FEATURES - Admin operation for updating cluster features

Unknown/Unsupported APIs (affected by this setting):

KIP-1000 Configuration APIs (bypass ACL checks):
- LIST_CLIENT_METRICS_RESOURCES (KIP-1000) - List client metrics configuration resources without DESCRIBE_CONFIGS permission
Internal/Admin APIs (not meant for client use):
- LEADER_AND_ISR - Internal leader election and ISR management
- STOP_REPLICA - Internal replica management
- UPDATE_METADATA - Internal metadata updates
- CONTROLLED_SHUTDOWN - Internal broker shutdown coordination
- WRITE_TXN_MARKERS - Internal transaction marker management
- DESCRIBE_QUORUM - Internal quorum management
- ENVELOPE - Internal request envelope handling
- UNREGISTER_BROKER - Internal broker registration management
- ADD_RAFT_VOTER - Internal Raft consensus management
- REMOVE_RAFT_VOTER - Internal Raft consensus management
Future Kafka APIs not yet implemented in Gateway
Any other APIs that may bypass Gateway’s security controls or don’t work correctly with Gateway features

Security implications: When GATEWAY_FEATURE_FLAGS_BLOCK_UNSUPPORTED_APIS=false (permissive mode):

Unsupported APIs are passed through to Kafka without Gateway processing
Configuration exposure: KIP-1000 APIs allow access to sensitive configuration without proper permissions
Internal API access: Internal/Admin APIs meant for broker-to-broker communication may be accessible to clients
Topic mapping and other Gateway features may not work correctly
Potential for unauthorized access to restricted resources and information disclosure

The KIP-932 share-group and KIP-1071 streams-group APIs are not affected by this setting — Gateway always blocks them, in both modes. When GATEWAY_FEATURE_FLAGS_BLOCK_UNSUPPORTED_APIS=true (restrictive mode):

All unsupported APIs are blocked at the Gateway level
Prevents security vulnerabilities: Blocks KIP-1000 APIs that bypass ACL checks
Prevents internal API access: Blocks internal/Admin APIs that should not be accessible to clients
Enhanced security through explicit allow-list approach
Applications must use only Gateway-supported APIs

Example of problematic situation: ListClientMetricsResources API bypasses ACL checks: When GATEWAY_FEATURE_FLAGS_BLOCK_UNSUPPORTED_APIS=false (permissive mode), clients can call the ListClientMetricsResources API without proper authorization. This API is designed to list all client metrics configuration resources in the cluster. Attack scenario:

Unauthorized client connects to Gateway without DESCRIBE_CONFIGS permission on CLUSTER resource
Client calls ListClientMetricsResources API directly
Gateway forwards the request to Kafka without ACL validation (since it’s not in the supported APIs list)
Kafka responds with complete list of client metrics configuration resources
Client receives sensitive configuration information including:
- All configured client metrics resources
- Internal cluster configuration details
- Resource names and configurations that should be protected

Security impact:

Information disclosure: Unauthorized access to sensitive cluster configuration
ACL bypass: Complete circumvention of Gateway’s permission system
Compliance violation: Access to restricted data without proper authorization
Reconnaissance: Attackers can enumerate cluster resources for further attacks

Why this happens: The ListClientMetricsResources API is not included in Gateway’s supported APIs list, so when permissive mode is enabled, it bypasses all Gateway security controls and is forwarded directly to Kafka without ACL validation.

This setting only affects unsupported APIs. APIs that are explicitly blocked for security or stability reasons (like consumer group management) will always be blocked, regardless of this setting.

Low-level network configuration

These variables should not be changed without consulting the Conduktor support team. They allow tuning and debugging uncommon network behavior.

Environment variable	Description	Default value
`GATEWAY_NETWORK_CONNECTION_BACKLOG`	TCP accept queue size (SO_BACKLOG). Limits pending new connections requests, between handshake and accept().	`1024`
`GATEWAY_NETWORK_MAX_MESSAGES_PER_READ`	Messages processed per event loop iteration. Prevents single channel from monopolizing resources.	`16`
`GATEWAY_NETWORK_MAX_FRAME_SIZE`	Maximum size of a single Kafka request/response frame. Prevents memory exhaustion from malformed/malicious large frames.	`104857600` (100 MB)
`GATEWAY_NETWORK_MAX_CONNECTIONS`	Maximum total concurrent established connections.	`2147483647`
`GATEWAY_NETWORK_MAX_PENDING_REQUESTS`	Maximum in-flight requests in the queue.	`5`
`GATEWAY_NETWORK_USE_POOLED_ALLOCATOR`	Whether to use pooled ByteBuf allocators for Netty I/O operations. Pooled allocators reuse buffers to reduce allocation overhead and GC pressure.	`true`
`GATEWAY_NETWORK_USE_DIRECT_BUFFERS`	Whether to use direct buffers for Netty I/O operations.	`true`

​Use the Gateway container

​Use a file

​Listeners

​Listeners: port specification format

​Listeners: SSL client authentication modes

​Listeners: zero-config mode

​Listeners: legacy configuration (deprecated)

​Load balancing

​Connect Gateway to Kafka

​Connection pooling

​Cluster switch failover

​Security and authentication

​SSL authentication

​OAuthbearer

​Principal resolver

​Plain authentication

​Security provider

​HTTP API

​Feature flags

​Topic ID support (preview)

​Incremental fetch sessions (preview)

​Incompatibilities

​Licensing

​Monitoring

​Audit

​Logging

​Product analytics

​Advanced configuration

​Threading

​Gateway internal timeout

​Graceful shutdown

​Internal topics

​Internal state

​Topic names

​Required topic configuration

​Data Quality topic configs

​API blocking modes

​Low-level network configuration

Use the Gateway container

Use a file

Listeners

Listeners: port specification format

Listeners: SSL client authentication modes

Listeners: zero-config mode

Listeners: legacy configuration (deprecated)

Load balancing

Connect Gateway to Kafka

Connection pooling

Cluster switch failover

Security and authentication

SSL authentication

OAuthbearer

Principal resolver

Plain authentication

Security provider

HTTP API

Feature flags

Topic ID support (preview)

Incremental fetch sessions (preview)

Incompatibilities

Licensing

Monitoring

Audit

Logging

Product analytics

Advanced configuration

Threading

Gateway internal timeout

Graceful shutdown

Internal topics

Internal state

Topic names

Required topic configuration

Data Quality topic configs

API blocking modes

Low-level network configuration