Skip to main content
Version: 8.3

Gateway configuration

The Zeebe Gateway can be configured similarly to the broker via the application.yaml file or environment variables. A complete gateway configuration template is available in the Zeebe repository.

Configure an embedded gateway

If you're configuring a gateway that is embedded inside of a broker (i.e. you've set zeebe.broker.gateway.enable), then you must use zeebe.broker.gateway.* instead of zeebe.gateway.* for any of the configuration options below. For environment variables this means you must use ZEEBE_BROKER_GATEWAY_* instead of ZEEBE_GATEWAY_*.

Conventions

Take the following conventions into consideration when working with the gateway configuration.

Byte sizes

Buffers and data values referencing sizing must be specified as strings and follow the following format: "10U" where U (unit) must be replaced with KB = Kilobytes, MB = Megabytes or GB = Gigabytes. If unit is omitted then the default unit is simply bytes.

For example, sendBufferSize = "16MB" creates a buffer of 16 Megabytes.

Time units

Timeouts and intervals must be specified either in the standard ISO-8601 format used by java.time.Duration, or as strings with the following format: "VU", where:

  • V is a numerical value (e.g. 1, 5, 10, etc.)
  • U is the unit, one of: ms = Millis, s = Seconds, m = Minutes, or h = Hours

Paths

Relative paths are resolved relative to the installation directory of the broker.

Configuration

We provide tables with environment variables, application properties, a description, and corresponding default values in the following sections. We also describe a few use cases for each type of configuration.

Configuration names are noted as the header of each documented section, while the field values represent properties to set the configuration.

For deploying purposes, it is easier to use environment variables. The following sections outline usage of these variables. As Helm is the recommended way to deploy Camunda 8, we will explain some configuration options here as well. Find more information about possible Zeebe Gateway Helm chart configurations here.

zeebe.gateway.network

The network configuration allows configuration of the host and port details for the gateway.

FieldDescriptionExample value
hostSets the host the gateway binds to. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_NETWORK_HOST.0.0.0.0
portSets the port the gateway binds to. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_NETWORK_PORT.26500
minKeepAliveIntervalSets the minimum keep alive interval. This setting specifies the minimum accepted interval between keep alive pings. This value must be specified as a positive integer followed by 's' for seconds, 'm' for minutes, or 'h' for hours. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_NETWORK_MINKEEPALIVEINTERVAL.30s
maxMessageSizeSets the maximum size of the incoming and outgoing messages (i.e. commands and events). Apply the same setting on the broker too, see ZEEBE_BROKER_NETWORK_MAXMESSAGESIZE. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_NETWORK_MAXMESSAGESIZE.4MB

YAML snippet

network:
host: 0.0.0.0
port: 26500
minKeepAliveInterval: 30s
maxMessageSize: 4MB

zeebe.gateway.cluster

As mentioned, the gateway needs to connect to the Zeebe brokers.

It is important to configure the cluster's initial contact point to the Zeebe brokers. You may set only one of the Zeebe brokers, but keep in mind that resiliency will be lower than using all the Zeebe brokers available. The corresponding environment variable is called ZEEBE_GATEWAY_CLUSTER_INITIALCONTACTPOINTS.

It is necessary to use the same cluster name for the broker and gateway. Otherwise, a connection will not be possible. The related configuration property is zeebe.gateway.cluster.clusterName and as an environment variable, it is called ZEEBE_GATEWAY_CLUSTER_CLUSTERNAME.

If you use the Helm charts, both properties are configured for you already.

FieldDescriptionExample value
initialContactPointsSets initial contact points (brokers), which the gateway should contact. The contact points of the internal network configuration must be specified. The format is [HOST:PORT]. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_INITIALCONTACTPOINTS specifying a comma-separated list of contact points.[ 192.168.1.22:26502, 192.168.1.32:26502 ]
contactPointWARNING: This setting is deprecated! Use initialContactPoints instead. Sets the broker the gateway should initial contact. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_CONTACTPOINT.127.0.0.1:26502
requestTimeoutSets the timeout of requests sent to the broker cluster. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_REQUESTTIMEOUT.15s
clusterNameSets name of the Zeebe cluster to connect to. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_CLUSTERNAME.zeebe-cluster
memberIdSets the member id of the gateway in the cluster. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERID.gateway
hostSets the host the gateway node binds to for internal cluster communication. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_HOST.0.0.0.0
portSets the port the gateway node binds to for internal cluster communication. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_PORT.26502
advertisedHostControls the advertised host; if omitted defaults to the host. This is particularly useful if your gateway stands behind a proxy. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_ADVERTISEDHOST.0.0.0.0
advertisedPortControls the advertised port; if omitted defaults to the port. This is particularly useful if your gateway stands behind a proxy. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_ADVERTISEDPORT.25602

YAML snippet

cluster:
initialContactPoints: 127.0.0.1:26502
contactPoint: 127.0.0.1:26502
requestTimeout: 15s
clusterName: zeebe-cluster
memberId: gateway
host: 0.0.0.0
port: 26502
advertisedHost: 0.0.0.0
advertisedPort: 25602

zeebe.gateway.cluster.membership

To configure how the gateway connects and distributes information with other nodes (brokers or gateways) via SWIM, the following properties can be used. It might be useful to increase timeouts for setups that encounter a high latency between nodes.

FieldDescriptionExample value
broadcastUpdatesConfigure whether to broadcast member updates to all members. If set to false, updates will be gossiped among the members. If set to true, the network traffic may increase but reduce the time to detect membership changes. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_BROADCASTUPDATES.false
broadcastDisputesConfigure whether to broadcast disputes to all members. If set to true, the network traffic may increase but reduce the time to detect membership changes. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_BROADCASTDISPUTES.true
notifySuspectConfigure whether to notify a suspect node on state changes. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_NOTIFYSUSPECT.false
gossipIntervalSets the interval at which the membership updates are sent to a random member. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_GOSSIPINTERVAL.250ms
gossipFanoutSets the number of members to which membership updates are sent at each gossip interval. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_GOSSIPFANOUT.2
probeIntervalSets the interval at which to probe a random member. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_PROBEINTERVAL.1s
probeTimeoutSets the timeout for a probe response. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_PROBETIMEOUT.100ms
suspectProbesSets the number of probes failed before declaring a member is suspect. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_SUSPECTPROBES.3
failureTimeoutSets the timeout for a suspect member is declared dead. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_FAILURETIMEOUT.10s
syncIntervalSets the interval at which this member synchronizes its membership information with a random member. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MEMBERSHIP_SYNCINTERVAL.10s

YAML snippet

membership:
broadcastUpdates: false
broadcastDisputes: true
notifySuspect: false
gossipInterval: 250ms
gossipFanout: 2
probeInterval: 1s
probeTimeout: 100ms
suspectProbes: 3
failureTimeout: 10s
syncInterval: 10s

zeebe.gateway.cluster.security

The cluster security configuration options allow securing communication between the gateway and other nodes in the cluster.

note

You can read more about intra-cluster security on its dedicated page.

FieldDescriptionExample value
enabledEnables TLS authentication between this gateway and other nodes in the cluster. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_SECURITY_ENABLED.false
certificateChainPathSets the path to the certificate chain file. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_SECURITY_CERTIFICATECHAINPATH.
privateKeyPathSets the path to the private key file location. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_SECURITY_PRIVATEKEYPATH.

YAML snippet

security:
enabled: false
certificateChainPath: null
privateKeyPath: null

zeebe.gateway.cluster.security.authentication

FieldDescriptionExample value
modeControls which authentication mode is active; supported modes are none and identity. If identity is set, authentication will be done using camunda-identity, which needs to be configured in the corresponding subsection. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_AUTHENTICATION_MODE.none

YAML snippet

security:
authentication:
mode: none

zeebe.gateway.cluster.security.authentication.identity

FieldDescriptionExample value
issuerBackendUrlThe URL to the auth provider backend, used to validate tokens. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_ISSUERBACKENDURL.http://keycloak:8080/auth/realms/camunda-platform
audienceThe required audience of the auth token. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_AUDIENCE.zeebe-api
typeThe identity auth type to apply, one of keycloak or auth0. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_TYPE.keycloak
baseUrlThe URL to the Identity instance. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_BASEURL.http://identity:8084

YAML snippet

security:
authentication:
mode: identity
identity:
issuerBackendUrl: http://keycloak:8080/auth/realms/camunda-platform
audience: zeebe-api
type: keycloak

zeebe.gateway.cluster.messageCompression

To configure the compression algorithm for all messages sent between the gateway and the brokers, the following property can be set. Available options are NONE, GZIP, and SNAPPY. This feature is useful when the network latency between the nodes is very high (for example, when nodes are deployed in different data centers).

When latency is high, the network bandwidth is severely reduced. Therefore, enabling compression helps improve the throughput. You need to decide between reducing bandwidth or reducing resources required for compression.

caution

When this flag is enabled, you must also enable compression in the standalone broker configuration. When there is no latency enabling, this may have a performance impact.

FieldDescriptionExample value
messageCompressionConfigure compression algorithm for all messages sent between the gateway and the brokers. Available options are NONE, GZIP, and SNAPPY. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_CLUSTER_MESSAGECOMPRESSION.NONE

YAML snippet

messageCompression: NONE

zeebe.gateway.threads

To handle many concurrent incoming requests, the user can do two things: scale the deployed gateways (if the standalone mode is in use), or increase the used resources and threads.

The Zeebe Gateway uses one thread by default, but this should be set to a higher number if the gateway doesn’t exhaust its available resources and doesn’t keep up with the load. The corresponding environment variables look like this: ZEEBE_GATEWAY_THREADS_MANAGEMENTTHREADS. During benchmarking and when increasing the thread count, it may also make sense to increase the given resources, which are quite small in the Helm chart.

For high availability and redundancy, two Zeebe Gateways are deployed by default with the Helm charts. To change that amount, set zeebe-gateway.replicas=2 to a different number. Increasing the number of gateway replicas to more than one enables the possibility for quick failover; in the case one gateway dies, the remaining gateway(s) can handle the traffic.

To explore how the gateway behaves, or what it does, metrics can be consumed. By default, the gateway exports Prometheus metrics, which can be scrapped under :9600/actuator/prometheus.

FieldDescriptionExample value
managementThreadsSets the number of threads the gateway will use to communicate with the broker cluster. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_THREADS_MANAGEMENTTHREADS.1

YAML snippet

threads:
managementThreads: 1

zeebe.gateway.security

The client security configuration options allow securing the communication between a gateway and clients.

note

You can read more about client-gateway security on its dedicated page.

FieldDescriptionExample value
enabledEnables TLS authentication between clients and the gateway. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_ENABLED.false
certificateChainPathSets the path to the certificate chain file. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_CERTIFICATECHAINPATH.
privateKeyPathSets the path to the private key file location. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_SECURITY_PRIVATEKEYPATH.

YAML snippet

security:
enabled: false
certificateChainPath:
privateKeyPath:

zeebe.gateway.longPolling

It's possible to configure gateway long-polling behavior. Read more on long-polling behavior here.

FieldDescriptionExample value
enabledEnables long polling for available jobs. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_LONGPOLLING_ENABLED.true

YAML snippet

longPolling:
enabled: true

zeebe.gateway.interceptors

It is possible to intercept requests in the gateway, which can be configured via environment variables or the application.yaml file. For more details, read about interceptors.

Each interceptor should be configured with the values described below:

FieldDescriptionExample value
idIdentifier for this interceptor. This setting can also be overridden using the environment variable `ZEEBE_GATEWAY_INTERCEPTORS_0_ID`.
jarPathPath (relative or absolute) to the JAR file containing the interceptor class and its dependencies. All classes must be compiled for the same language version as Zeebe or lower. This setting can also be overridden using the environment variable `ZEEBE_GATEWAY_INTERCEPTORS_0_JARPATH`.
classNameEntry point of the interceptor, a class which must:
  • implement io.grpc.ServerInterceptor
  • have public visibility
  • have a public default constructor (i.e. no-arg constructor)
  • This setting can also be overridden using the environment variable `ZEEBE_GATEWAY_INTERCEPTORS_0_CLASSNAME`.

    YAML snippet

    interceptors:
    id: null
    jarPath: null
    className: null

    zeebe.gateway.multiTenancy

    Multi-tenancy in Zeebe can be configured with the following configuration properties. Read more in the multi-tenancy documentation.

    note

    For now, multi-tenancy is only supported in combination with Identity. To use multi-tenancy, you must set authentication.mode to 'identity' and specify the identity.baseUrl as well.

    note

    If you are using an embedded gateway, refer to the broker configuration guide.

    FieldDescriptionExample value
    enabledEnables multi-tenancy for the cluster. This setting can also be overridden using the environment variable ZEEBE_GATEWAY_MULTITENANCY_ENABLED.true

    YAML snippet

    multiTenancy:
    enabled: true