Version: 8.5

Broker configuration

A complete broker configuration template is available in the Zeebe repo.

Conventions

Take the following conventions into consideration when working with the broker 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.

Example: sendBufferSize = "16MB" (creates a buffer of 16 Megabytes)

Time units

Timeouts, intervals, and the likes, 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.

note

The Zeebe Broker is a Spring Boot application. As such, many common Spring Boot properties will work out of the box.

Additionally, its REST server is a reactive Spring Boot server (powered by WebFlux), and can be configured using the standard server.* properties, as well as the usual WebFlux properties. Its management server (for example, where actuator endpoints live) is configured as a child application context, and is also a reactive WebFlux server. It can be configured via management.server.* properties.

Finally, the REST server is only serving requests if, and only if, the embedded gateway is enabled via zeebe.broker.gateway.enable: true.

server

The server configuration allows you to configure the main REST server. Below are a few common ones, but you can find a more exhaustive list in the official Spring documentation.

Field	Description	Example value
host	Sets the host the REST server binds to. This setting can also be overridden using the environment variable `SERVER_HOST`.	0.0.0.0
port	Sets the port the REST server binds to. This setting can also be overridden using the environment variable `SERVER_PORT`.	8080

server.compression

Field	Description	Example value
enabled	If true, enables compression of responses for the REST API. This setting can also be overridden using the environment variable `SERVER_COMPRESION_ENABLED`.	false

server.ssl

Allows you to configure the SSL security for the REST server.

Field	Description	Example value
enabled	If true, enables TLS for the REST API. This setting can also be overridden using the environment variable `SERVER_SSL_ENABLED`.	false
certificate	The path to a PEM encoded certificate. This setting can also be overridden using the environment variable `SERVER_SSL_CERTIFICATE`.
certificate-private-key	The path to a PKCS1 or PKCS8 private key for the configured certificate. This setting can also be overridden using the environment variable `SERVER_SSL_CERTIFICATEPRIVATEKEY`.

YAML snippet

server:
  host: 0.0.0.0
  port: 8080
  compression:
    enabled: true
  ssl:
    enabled: true
    certificate: /path/to/my/cert.pem
    certificate-private-key: /path/to/my/private.key

spring.webflux

Field	Description	Example value
base-path	The context path prefix for all REST API requests. For example, if you configure `/zeebe`, then the client's REST address would be `http://localhost:8080/zeebe`. This setting can also be overridden using the environment variable `SPRING_WEBFLUX_BASEPATH`.	`/`

YAML snippet

spring.webflux:
  base-path: /

management.server

The management.server configuration allows you to configure the management server.

Field	Description	Example value
host	Sets the host the management server binds to. This setting can also be overridden using the environment variable `MANAGEMENT_SERVER_HOST`.	0.0.0.0
port	Sets the port the management server binds to. This setting can also be overridden using the environment variable `MANAGEMENT_SERVER_PORT`.	8080
base-path	The context path prefix for all management endpoints. For example, if you configure `/zeebe`, your actuator endpoints will be at `http://localhost:9600/zeebe/actuator/configprops`. This setting can also be overridden using the environment variable `MANAGEMENT_SERVER_BASEPATH`.	`/`

YAML snippet

management.server:
  host: 0.0.0.0
  port: 9600
  base-path: /

zeebe.broker.gateway

To configure the embedded gateway, see Gateway config docs.

Field	Description	Example value
enable	Enable the embedded gateway to start on broker startup. This setting can also be overridden using the environment variable `ZEEBE_BROKER_GATEWAY_ENABLE`.	false

YAML snippet

broker:
  gateway:
    enable: false

zeebe.broker.network

This section contains the network configuration. Particularly, it allows to configure the hosts and ports the broker should bind to. The broker exposes two sockets:

command: the socket which is used for gateway-to-broker communication
internal: the socket which is used for broker-to-broker communication

Field	Description	Example Value
host	Controls the default host the broker should bind to. Can be overwritten on a per binding basis for client, management and replication. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_HOST`.	0.0.0.0
advertisedHost	Controls the advertised host (the contact point advertised to other brokers); if omitted defaults to the host. This is particularly useful if your broker stands behind a proxy. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_ADVERTISEDHOST`.	0.0.0.0
portOffset	If a port offset is set it will be added to all ports specified in the config or the default values. This is a shortcut to not always specifying every port. The offset will be added to the second last position of the port, as Zeebe requires multiple ports. As example a portOffset of 5 will increment all ports by 50, i.e. 26500 will become 26550 and so on. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_PORTOFFSET`.	0
maxMessageSize	Sets the maximum size of the incoming and outgoing messages (i.e. commands and events). This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_MAXMESSAGESIZE`.	4MB

YAML snippet

network:
  host: 0.0.0.0
  advertisedHost: 0.0.0.0
  portOffset: 0
  maxMessageSize: 4MB

zeebe.broker.network.security

Field	Description	Example Value
enabled	Enables TLS authentication between this gateway and other nodes in the cluster. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_SECURITY_ENABLED`.	false
certificateChainPath	Sets the path to the certificate chain file. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_SECURITY_CERTIFICATECHAINPATH`.
privateKeyPath	Sets the path to the private key file location. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_SECURITY_PRIVATEKEYPATH`.

YAML snippet

security:
  enabled: false
  certificateChainPath:
  privateKeyPath:

zeebe.broker.network.commandApi

Field	Description	Example Value
host	Overrides the host used for gateway-to-broker communication. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_COMMANDAPI_HOST`.	0.0.0.0
port	Sets the port used for gateway-to-broker communication. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_COMMANDAPI_PORT`.	26501
advertisedHost	Controls the advertised host; if omitted defaults to the host. This is particularly useful if your broker stands behind a proxy. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_COMMANDAPI_ADVERTISEDHOST`.	0.0.0.0
advertisedPort	Controls the advertised port; if omitted defaults to the port. This is particularly useful if your broker stands behind a proxy. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_COMMANDAPI_ADVERTISEDPORT`.	25601

YAML snippet

commandApi:
  host: 0.0.0.0
  port: 26501
  advertisedHost: 0.0.0.0
  advertisedPort: 25601

zeebe.broker.network.internalApi

Field	Description	Example Value
host	Overrides the host used for internal broker-to-broker communication. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_INTERNALAPI_HOST`.	0.0.0.0
port	Sets the port used for internal broker-to-broker communication. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_INTERNALAPI_PORT`.	26502
advertisedHost	Controls the advertised host; if omitted defaults to the host. This is particularly useful if your broker stands behind a proxy. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_INTERNALAPI_ADVERTISEDHOST`.	0.0.0.0
advertisedPort	Controls the advertised port; if omitted defaults to the port. This is particularly useful if your broker stands behind a proxy. This setting can also be overridden using the environment variable `ZEEBE_BROKER_NETWORK_INTERNALAPI_ADVERTISEDPORT`.	25602

YAML snippet

internalApi:
  host: 0.0.0.0
  port: 26502
  advertisedHost: 0.0.0.0
  advertisedPort: 25602

zeebe.broker.data

This section allows to configure Zeebe's data storage. Data is stored in "partition folders". A partition folder has the following structure:

partitions
└── 1              (root partition folder)
    ├── 1.log
    ├── 2.log
    └── snapshots
        └── <snapshot-id>
                    └── xx.sst
    └── runtime
        └── yy.sst

Field	Description	Example Value
directory	Specify the directory in which data is stored. This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_DIRECTORY.	data
runtimeDirectory	Specify the directory in which runtime is stored. By default runtime is stored in `directory` for data. If runtimeDirectory is configured, then the configured directory will be used. It will have a subdirectory for each partition to store its runtime. There is no need to store runtime in a persistent storage. This configuration allows to split runtime to another disk to optimize for performance and disk usage. Note: If runtime is another disk than the data directory, files need to be copied to data directory while taking snapshot. This may impact disk i/o or performance during snapshotting. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_RUNTIMEDIRECTORY`.	null
logSegmentSize	The size of data log segment files. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_LOGSEGMENTSIZE`.	128MB
snapshotPeriod	How often we take snapshots of streams (time unit). This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_SNAPSHOTPERIOD`.	5m

YAML snippet

data:
  directory: data
  runtimeDirectory: null
  logSegmentSize: 128MB
  snapshotPeriod: 5m

zeebe.broker.data.disk

Field	Description	Example Value
enableMonitoring	Configure disk monitoring to prevent getting into a non-recoverable state due to out of disk space. When monitoring is enabled, the broker rejects commands and pause replication when the required freeSpace is not available. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_DISK_ENABLEMONITORING`	true
monitoringInterval	Sets the interval at which the disk usage is monitored. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_DISK_MONITORINGINTERVAL`	1s

YAML snippet

disk:
  enableMonitoring: true
  monitoringInterval: 1s

zeebe.broker.data.disk.freeSpace

Field	Description	Example Value
processing	When the free space available is less than this value, this broker rejects all client commands and pause processing. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_DISK_FREESPACE_PROCESSING`	2GB
replication	When the free space available is less than this value, broker stops receiving replicated events. This value must be less than freeSpace.processing. It is recommended to configure free space large enough for at least one log segment and one snapshot. This is because a partition needs enough space to take a new snapshot to be able to compact the log segments to make disk space available again. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_DISK_FREESPACE_REPLICATION`	1GB

YAML snippet

disk:
  freeSpace:
    processing: 2GB
    replication: 1GB

zeebe.broker.data.backup

Configure backup store.

note

Use the same configuration on all brokers of this cluster.

Field	Description	Example Value
store	Set the backup store type. Supported values are [NONE, S3, GCS, AZURE]. Default value is NONE. When NONE, no backup store is configured and no backup will be taken. Use S3 to use any S3 compatible storage, including, but not limited to, Amazon S3. Use GCS to use Google Cloud Storage. Use AZURE to employ Azure Cloud Storage. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_STORE`.	NONE

YAML snippet

backup:
  store: NONE

zeebe.broker.data.backup.s3

Configure the following if store is set to s3.

note

You can use any S3 compatible storage, including, but not limited to, Amazon S3.

Field	Description	Example Value
bucketName	Name of the bucket where the backup will be stored. The bucket must be already created. The bucket must not be shared with other zeebe clusters. bucketName must not be empty. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME`.
endpoint	Configure URL endpoint for the store. If no endpoint is provided, it will be determined based on the configured region. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_ENDPOINT`.
region	Configure region. If no region is provided it will be determined as documented by your S3 compatible storage provider. If you use Amazon S3, it will be determined as documented. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_REGION`
accessKey	Configure access credentials. If either accessKey or secretKey is not provided, it will be determined as documented, not based on your S3 compatible storage provider. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_ACCESSKEY`.
secretKey	This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_SECRETKEY`.
apiCallTimeout	Configure a maximum duration for all S3 client API calls. Lower values will ensure that failed or slow API calls don't block other backups but may increase the risk that backups can't be stored if uploading parts of the backup takes longer than the configured timeout. Amazon S3 users can refer here. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_APICALLTIMEOUT`.	PT180S
forcePathStyleAccess	When enabled, forces the s3 client to use path-style access. By default, the client will automatically choose between path-style and virtual-hosted-style. Should only be enabled if the s3 compatible storage cannot support virtual-hosted-style. Refer to your S3 compatible storage provider or the Amazon S3 docs for more information. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_FORCEPATHSTYLEACCESS`.	false
compression	When set to an algorithm such as 'zstd', enables compression of backup contents. When not set or set to 'none', backup content is not compressed. Enabling compression reduces the required storage space for backups in S3 but also increases the impact on CPU and disk utilization while taking a backup. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_COMPRESSION`	none
basePath	When set, all objects in the bucket will use this prefix. Must be non-empty and not start or end with '/'. Useful for using the same bucket for multiple Zeebe clusters. In this case, basePath must be unique. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_S3_BASEPATH`.

YAML snippet

backup:
  store: s3
  s3:
    bucketName: null
    endpoint: null
    region: null
    secretKey: null
    apiCallTimeout: PT180S
    forcePathStyleAccess: false
    compression: none
    basePath: null

zeebe.broker.data.backup.gcs

Configure the following if store is set to GCS.

Field	Description	Example Value
bucketName	Name of the bucket where the backup will be stored. The bucket must already exist. The bucket must not be shared with other Zeebe clusters unless basePath is also set. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_GCS_BUCKETNAME`.
basePath	When set, all blobs in the bucket will use this prefix. Useful for using the same bucket for multiple Zeebe clusters. In this case, basePath must be unique. Should not start or end with '/' character. Must be non-empty and not consist of only '/' characters. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_GCS_BASEPATH`.
host	When set, this overrides the host that the GCS client connects to. By default, this is not set because the client can automatically discover the correct host to connect to. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_GCS_HOST`
auth	Configures which authentication method is used for connecting to GCS. Can be either 'auto' or 'none'. Choosing 'auto' means that the GCS client uses application default credentials which automatically discovers appropriate credentials from the runtime environment: https://cloud.google.com/docs/authentication/application-default-credentials. Choosing 'none' means that no authentication is attempted which is only applicable for testing with emulated GCS. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_GCS_AUTH`.	auto

YAML snippet

backup:
  store: gcs
  gcs:
    bucketName: null
    basePath: null
    host: null
    auth: auto

zeebe.broker.data.backup.azure

Configure the following if store is set to Azure.

Field	Description	Example Value
endpoint	Name of the endpoint where the backup will be stored. Sets the blob service endpoint. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_AZURE_ENDPOINT`.
accountName	Account name used to connect to the service. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_AZURE_ACCOUNTNAME`.
accountKey	Account key used to connect to the service. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_AZURE_ACCOUNTKEY`.
connectionString	The connection string to connect to the service. If this is defined, it will override the account name, account key, and endpoint. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_AZURE_CONNECTIONSTRING`.
basePath	Used to define the container name where the blobs will be saved. This basePath cannot be null. This setting can also be overridden using the environment variable `ZEEBE_BROKER_DATA_BACKUP_AZURE_BASEPATH`.

YAML snippet

backup:
  store: azure
  azure:
    endpoint: null
    accountName: null
    accountKey: null
    connectionString: null
    basePath: null

zeebe.broker.cluster

This section contains all cluster related configurations, to setup a zeebe cluster.

Field	Description	Example Value
nodeId	Specifies the unique id of this broker node in a cluster. The id should be between 0 and number of nodes in the cluster (exclusive). This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_NODEID`.	0
partitionsCount	Controls the number of partitions, which should exist in the cluster. This can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_PARTITIONSCOUNT`.	1
replicationFactor	Controls the replication factor, which defines the count of replicas per partition. The replication factor cannot be greater than the number of nodes in the cluster. This can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_REPLICATIONFACTOR`.	1
clusterSize	Specifies the zeebe cluster size. This value is used to determine which broker is responsible for which partition. This can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_CLUSTERSIZE`.	1
initialContactPoints	Allows to specify a list of known other nodes to connect to on startup. The contact points of the internal network configuration must be specified. The format is [HOST:PORT]. To guarantee the cluster can survive network partitions, all nodes must be specified as initial contact points. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_INITIALCONTACTPOINTS` specifying a comma-separated list of contact points. Default is empty list.	[ 192.168.1.22:26502, 192.168.1.32:26502 ]
clusterName	Allows to specify a name for the cluster. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_CLUSTERNAME`.	zeebe-cluster
heartbeatInterval	Configure heartbeatInterval. The leader sends a heartbeat to a follower every heartbeatInterval. Note: This is an advanced setting. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_HEARTBEATINTERVAL`.	250ms
electionTimeout	Configure electionTimeout. If a follower does not receive a heartbeat from the leader with in an election timeout, it can start a new leader election. electionTimeout should be greater than configured heartbeatInterval. When the electionTimeout is large, there will be delay in detecting a leader failure. When the electionTimeout is small, it can lead to false positives when detecting leader failures and thus leading to unnecessary leader changes. If the network latency between the nodes is high, it is recommended to have a higher election latency. Note: This is an advanced setting. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_ELECTIONTIMEOUT`.	2500ms

YAML snippet

cluster:
  nodeId: 0
  partitionsCount: 1
  replicationFactor: 1
  clusterSize: 1
  initialContactPoints: []
  clusterName: zeebe-cluster
  heartbeatInterval: 250ms
  electionTimeout: 2500ms

zeebe.broker.cluster.raft

Field	Description	Example Value
raft	Configure raft properties.
enablePriorityElection	When this flag is enabled, the leader election algorithm attempts to elect the leaders based on a pre-defined priority. As a result, it tries to distributed the leaders uniformly across the brokers. Note that it is only a best-effort strategy. It is not guaranteed to be a strictly uniform distribution. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_RAFT_ENABLEPRIORITYELECTION`.	true

YAML snippet

cluster:
  raft: enablePriorityElection = true

zeebe.broker.cluster.flush

Field	Description	Example Value
flush	Configures how often data is explicitly flushed to disk. By default, for a given partition, data is flushed on every leader commit, and every follower append. This is to ensure consistency across all replicas. Disabling this can cause inconsistencies, and at worst, data corruption or data loss scenarios. The default behavior is optimized for safety, and flushing occurs on every leader commit and follower append in a synchronous fashion. You can introduce a delay to reduce the performance penalty of flushing via `delayTime`.
enabled	If false, explicit flushing of the Raft log is disabled, and flushing only occurs right before a snapshot is taken. You should only disable explicit flushing if you are willing to accept potential data loss at the expense of performance. Before disabling it, try the delayed options, which provide a trade-off between safety and performance. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_RAFT_FLUSH_ENABLED`.	true
delayTime	If the delay is > 0, then flush requests are delayed by at least the given period. It is recommended that you find the smallest delay here with which you achieve your performance goals. It's also likely that anything above 30s is not useful, as this is the typical default flush interval for the Linux OS. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_RAFT_FLUSH_DELAYTIME`.	0s

YAML snippet

cluster:
  flush:
    enabled: true
    delayTime: 0s

zeebe.broker.cluster.membership

Configure parameters for SWIM protocol which is used to propagate cluster membership information among brokers and gateways.

Field	Example Value	Description
broadcastUpdates	Configure 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 it reduce the time to detect membership changes. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_BROADCASTUPDATES`.	false
broadcastDisputes	Configure whether to broadcast disputes to all members. If set to true the network traffic may increase but it reduce the time to detect membership changes. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_BROADCASTDISPUTES`.	true
notifySuspect	Configure whether to notify a suspect node on state changes. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_NOTIFYSUSPECT`.	false
gossipInterval	Sets the interval at which the membership updates are sent to a random member. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_GOSSIPINTERVAL`.	250ms
gossipFanout	Sets 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_BROKER_CLUSTER_MEMBERSHIP_GOSSIPFANOUT`.	2
probeInterval	Sets the interval at which to probe a random member. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_PROBEINTERVAL`.	1s
probeTimeout	Sets the timeout for a probe response. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_PROBETIMEOUT`.	100ms
suspectProbes	Sets the number of probes failed before declaring a member is suspect. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_SUSPECTPROBES`.	3
failureTimeout	Sets the timeout for a suspect member is declared dead. This setting can also be overridden using the environment variable `ZEEBE_BROKER_CLUSTER_MEMBERSHIP_FAILURETIMEOUT`.	10s
syncInterval	Sets 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_BROKER_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.broker.cluster.messageCompression

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. Hence enabling compression helps to improve the throughput.

caution

When there is no latency enabling this may have a performance impact.

note

When this flag is enables, you must also enable compression in standalone broker configuration.

Field	Description	Example Value
messageCompression	Configure 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_BROKER_CLUSTER_MESSAGECOMPRESSION`.	NONE

YAML snippet

messageCompression: NONE

zeebe.broker.threads

Field	Example Value	Description
cpuThreadCount	Controls the number of non-blocking CPU threads to be used. WARNING: You should never specify a value that is larger than the number of physical cores available. Good practice is to leave 1-2 cores for ioThreads and the operating system (it has to run somewhere). For example, when running Zeebe on a machine which has 4 cores, a good value would be 2. This setting can also be overridden using the environment variable `ZEEBE_BROKER_THREADS_CPUTHREADCOUNT`.	2
ioThreadCount	Controls the number of io threads to be used. These threads are used for workloads that write data to disk. While writing, these threads are blocked which means that they yield the CPU. This setting can also be overridden using the environment variable `ZEEBE_BROKER_THREADS_IOTHREADCOUNT`.	2

YAML snippet

threads:
  cpuThreadCount: 2
  ioThreadCount: 2

zeebe.broker.backpressure

Field	Description	Example Value
enabled	Set this to enable or disable backpressure. When enabled the broker rejects user requests when the number of inflight requests is greater than than the "limit". The value of the "limit" is determined based on the configured algorithm. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_ENABLED`.	true
useWindowed	if enabled - will use the average latencies over a window as the current latency to update the limit. It is not recommended to enable this when the algorithm is aimd. This setting is not applicable to fixed limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_USEWINDOWED`.	true
algorithm	The algorithm configures which algorithm to use for the backpressure. It should be one of vegas, aimd, fixed, gradient, or gradient2. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_ALGORITHM`.	aimd

YAML snippet

backpressure:
  enabled: true
  useWindowed: true
  algorithm: aimd

zeebe.broker.backpressure.aimd

Field	Description	Example Value
requestTimeout	The limit will be reduced if the observed latency is greater than the requestTimeout. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_AIMD_REQUESTTIMEOUT`.	200ms
initialLimit	The initial limit to be used when the broker starts. The limit will be reset to this value when the broker restarts. This setting can also be overridden using the environment `ZEEBE_BROKER_BACKPRESSURE_AIMD_INITIALLIMIT`.	100
minLimit	The minimum limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_AIMD_MINLIMIT`.	1
maxLimit	The maximum limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_AIMD_MAXLIMIT`.	1000
backoffRatio	The backoffRatio is a double value x such that x is between 0 and 1. It determines the factor by which the limit is decreased. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_AIMD_BACKOFFRATIO`.	0.9

YAML snippet

backpressure:
  algorithm: aimd
  aimd:
    requestTimeout: 200ms
    initialLimit: 100
    minLimit: 1
    maxLimit: 1000
    backoffRatio: 0.9

zeebe.broker.backpressure.fixed

Field	Description	Example Value
limit	Set a fixed limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_FIXED_LIMIT`.	20

YAML snippet

backpressure:
  algorithm: fixed
  fixed:
    limit: 20

zeebe.broker.backpressure.vegas

Field	Description	Example Value
initialLimit	The initial limit to be used when the broker starts. The limit will be reset to this value when the broker restarts. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_VEGAS_INITIALLIMIT`.	20
alpha	The limit is increased if the queue size is less than this value. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_VEGAS_ALPHA`.	3
beta	The limit is decreased if the queue size is greater than this value. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_VEGAS_BETA`.	6

YAML snippet

backpressure:
  algorithm: vegas
  vegas:
    initialLimit: 20
    alpha: 3
    beta: 6

zeebe.broker.backpressure.gradient

Field	Description	Example Value
minLimit	The minimum limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_GRADIENT_MINLIMIT`.	10
initialLimit	The initial limit to be used when the broker starts. The limit will be reset to this value when the broker restarts. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_GRADIENT_INITIALLIMIT`.	20
rttTolerance	Tolerance for changes from minimum latency. A value ≥ 1.0 indicating how much change from minimum latency is acceptable before reducing the limit. For example, a value of 2.0 means that a 2x increase in latency is acceptable. This setting can also be overridden using the environment variable ZEEBE_BROKER_BACKPRESSURE_GRADIENT_RTTTOLERANCE	2.0

YAML snippet

backpressure:
  algorithm: gradient
  gradient:
    minLimit: 10
    initialLimit: 20
    rttTolerance: 2.0

zeebe.broker.backpressure.gradient2

Field	Description	Example Value
minLimit	The minimum limit. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_GRADIENT2_MINLIMIT`.	10
initialLimit	The initial limit to be used when the broker starts. The limit will be reset to this value when the broker restarts. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_GRADIENT2_INITIALLIMIT`.	20
rttTolerance	Tolerance for changes from minimum latency. A value ≥ 1.0 indicating how much change from minimum latency is acceptable before reducing the limit. For example, a value of 2.0 means that a 2x increase in latency is acceptable. This setting can also be overridden using the environment variable `ZEEBE_BROKER_BACKPRESSURE_GRADIENT2_RTTTOLERANCE`.	2.0
longWindow	longWindow is the length of the window (the number of samples) to calculate the exponentially smoothed average latency. This setting can also be overridden using the environment `ZEEBE_BROKER_BACKPRESSURE_GRADIENT2_LONGWINDOW`.	600

YAML snippet

backpressure:
  algorithm: gradient2
  gradient2:
    minLimit: 10
    initialLimit: 20
    rttTolerance: 2.0
    longWindow: 600

zeebe.broker.exporters

Each exporter should be configured following this template:

Field	Description	Example Value
exporters	Configure exporters below
jarPath	path to the JAR file containing the exporter class. JARs are only loaded once, so you can define two exporters that point to the same JAR, with the same class or a different one, and use args to parametrize its instantiation.
className	entry point of the exporter, a class which must extend the io.camunda.zeebe.exporter.Exporter interface. A nested table as "args:" will allow you to inject arbitrary arguments into your class through the use of annotations. These setting can also be overridden using the environment variables "`ZEEBE_BROKER_EXPORTERS_`[exporter name]_..."

YAML snippet

exporters:
  jarPath:
  className:

zeebe.broker.exporters.elasticsearch

An example configuration for the Elasticsearch exporter can be found here.

zeebe.broker.exporters.opensearch (OpenSearch Exporter)

An example configuration for the OpenSearch exporter can be found here.

zeebe.broker.processing

Field	Description	Example Value
maxCommandsInBatch	Sets the maximum number of commands that processed within one batch. The processor will process until no more follow up commands are created by the initial command or the configured limit is reached. By default, up to 100 commands are processed in one batch. Can be set to 1 to disable batch processing. Must be a positive integer number. Note that the resulting batch size will contain more entries than this limit because it includes follow up events. When resulting batch size is too large (see maxMessageSize), processing will be rolled back and retried with a smaller maximum batch size. Lowering the command limit can reduce the frequency of rollback and retry. This setting can also be overridden using the environment variable `ZEEBE_BROKER_PROCESSING_MAXCOMMANDSINBATCH`.	100

YAML snippet

processing: maxCommandsInBatch = 100

Experimental configuration

See the experimental section of the broker.yaml.template.

Be aware that all configuration's which are part of the experimental section are subject to change and can be dropped at any time.

Multitenancy configuration

For an embedded gateway setup, any gateway property can be passed along to the StandaloneBroker by prefixing zeebe.broker.

zeebe.broker.gateway.multitenancy

Multi-tenancy in Zeebe can be configured with the following configuration properties. Multi-tenancy is disabled by default. 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 camunda.identity.baseUrl property or the corresponding Camunda Identity environment variable as well.

note

If you are using a standalone gateway, refer to the gateway configuration guide.

Field	Description	Example value
enabled	Enable multitenancy in the embedded gateway. This setting can also be overridden using the environment variable `ZEEBE_BROKER_GATEWAY_MULTITENANCY_ENABLED`.	false

YAML snippet

broker:
  gateway:
    multitenancy:
      enabled: false

zeebe.broker.gateway.security.authentication

Field	Description	Example value
mode	Controls 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_BROKER_GATEWAY_SECURITY_AUTHENTICATION_MODE`.	none

YAML snippet

security:
  authentication:
    mode: none

zeebe.broker.gateway.security.authentication.identity

note

The Zeebe configuration properties for Camunda Identity are deprecated as of version 8.4.0. Use the dedicated Camunda Identity properties or the corresponding environment variables.

Field	Description	Example value
issuerBackendUrl	The URL to the auth provider backend, used to validate tokens. This setting can also be overridden using the environment variable `ZEEBE_BROKER_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_ISSUERBACKENDURL`.	http://keycloak:8080/auth/realms/camunda-platform
audience	The required audience of the auth token. This setting can also be overridden using the environment variable `ZEEBE_BROKER_GATEWAY_SECURITY_AUTHENTICATION_IDENTITY_AUDIENCE`.	zeebe-api
baseUrl	The URL to the Identity instance. This setting can also be overridden using the environment variable `ZEEBE_BROKER_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

Conventions​

Byte sizes​

Time units​

Paths​

Configuration​

server​

server.compression​

server.ssl​

YAML snippet​

spring.webflux​

YAML snippet​

management.server​

YAML snippet​

zeebe.broker.gateway​

YAML snippet​

zeebe.broker.network​

YAML snippet​

zeebe.broker.network.security​

YAML snippet​

zeebe.broker.network.commandApi​

YAML snippet​

zeebe.broker.network.internalApi​

YAML snippet​

zeebe.broker.data​

YAML snippet​

zeebe.broker.data.disk​

YAML snippet​

zeebe.broker.data.disk.freeSpace​

YAML snippet​

zeebe.broker.data.backup​

YAML snippet​

zeebe.broker.data.backup.s3​

YAML snippet​

zeebe.broker.data.backup.gcs​

YAML snippet​

zeebe.broker.data.backup.azure​

YAML snippet​

zeebe.broker.cluster​

YAML snippet​

zeebe.broker.cluster.raft​

YAML snippet​

zeebe.broker.cluster.flush​

YAML snippet​

zeebe.broker.cluster.membership​

YAML snippet​

zeebe.broker.cluster.messageCompression​

YAML snippet​

zeebe.broker.threads​

YAML snippet​

zeebe.broker.backpressure​

YAML snippet​

zeebe.broker.backpressure.aimd​

YAML snippet​

zeebe.broker.backpressure.fixed​

YAML snippet​

zeebe.broker.backpressure.vegas​

YAML snippet​

zeebe.broker.backpressure.gradient​

YAML snippet​

zeebe.broker.backpressure.gradient2​

YAML snippet​

zeebe.broker.exporters​

YAML snippet​

zeebe.broker.exporters.elasticsearch​

zeebe.broker.exporters.opensearch (OpenSearch Exporter)​

zeebe.broker.processing​

YAML snippet​

Experimental configuration​

Multitenancy configuration​

zeebe.broker.gateway.multitenancy​

YAML snippet​

zeebe.broker.gateway.security.authentication​

YAML snippet​

zeebe.broker.gateway.security.authentication.identity​

YAML snippet​

Conventions

Byte sizes

Time units

Paths

Configuration

server

server.compression

server.ssl

YAML snippet

spring.webflux

YAML snippet

management.server

YAML snippet

zeebe.broker.gateway

YAML snippet

zeebe.broker.network

YAML snippet

zeebe.broker.network.security

YAML snippet

zeebe.broker.network.commandApi

YAML snippet

zeebe.broker.network.internalApi

YAML snippet

zeebe.broker.data

YAML snippet

zeebe.broker.data.disk

YAML snippet

zeebe.broker.data.disk.freeSpace

YAML snippet

zeebe.broker.data.backup

YAML snippet

zeebe.broker.data.backup.s3

YAML snippet

zeebe.broker.data.backup.gcs

YAML snippet

zeebe.broker.data.backup.azure

YAML snippet

zeebe.broker.cluster

YAML snippet

zeebe.broker.cluster.raft

YAML snippet

zeebe.broker.cluster.flush

YAML snippet

zeebe.broker.cluster.membership

YAML snippet

zeebe.broker.cluster.messageCompression

YAML snippet

zeebe.broker.threads

YAML snippet

zeebe.broker.backpressure

YAML snippet

zeebe.broker.backpressure.aimd

YAML snippet

zeebe.broker.backpressure.fixed

YAML snippet

zeebe.broker.backpressure.vegas

YAML snippet

zeebe.broker.backpressure.gradient

YAML snippet

zeebe.broker.backpressure.gradient2

YAML snippet

zeebe.broker.exporters

YAML snippet

zeebe.broker.exporters.elasticsearch

zeebe.broker.exporters.opensearch (OpenSearch Exporter)

zeebe.broker.processing

YAML snippet

Experimental configuration

Multitenancy configuration

zeebe.broker.gateway.multitenancy

YAML snippet

zeebe.broker.gateway.security.authentication

YAML snippet

zeebe.broker.gateway.security.authentication.identity

YAML snippet