This document describes the setup of Camunda Optimize Cluster which is useful formerly in a failover scenario but also provides means of load-balancing in terms of distributing import and user load.


There are two configuration requirements to address in order to operate Camunda Optimize successfully in a cluster scenario. Both of these aspects are explained in detail in the following subsections.

1. Import - Define Importing instance

It is important to configure the cluster in the sense that only one instance at a time is actively importing from a particular Camunda BPM Platform engine.


If more than one instance is importing data from one and the same Camunda BPM Platform engine concurrently inconsistencies can occur.

The configuration property engines.${engineAlias}.importEnabled allows to disable the import from a particular configured engine.

Given a simple failover cluster consisting of two instances connected to one engine, the engine configurations in the environment-config.yaml would look like the following:

Instance 1 (import from engine default enabled):

    name: default
    rest: 'http://localhost:8080/engine-rest'
    importEnabled: true

Instance 2 (import from engine default disabled):

    name: default
    rest: 'http://localhost:8080/engine-rest'
    importEnabled: false

  enabled: false

Note that the second non-importing instance has the history cleanup disabled. It is strongly recommmended to do that for all non-importing Optimize instances in the cluster to prevent any conflicts when the history cleanup is performed.

2. Distributed User Sessions - Configure shared secret token

If more than one Camunda Optimize instance are accessible by users for e.g. a failover scenario a shared secret token needs to be configured for all of the instances. This enables distributed sessions among all instances and users do not loose their session when being routed to another instance.

The relevant configuration property is auth.token.secret which needs to be configured in the environment-configuration.yaml of each Camunda Optimize instance that is part of the cluster.

It is recommended to use a secret token with at least a length of 64 characters at best generated using a good enough random number generator like for example the one provided by /dev/urandom on Linux systems.

The following example command would generate a 64 character random string:

< /dev/urandom tr -dc A-Za-z0-9 | head -c64; echo

The corresponding environment-config.yaml entry would look the same for all instances of the cluster:

    secret: '<your secret 64 character string>'

Example Setup

The tiniest cluster setup consisting of one importing instance from a given default engine and another instance where the import is disabled would look like the following:

The HTTP/S Load-Balancer would route user requests to either of the two instances, while Optimize #1 would also care about importing data from the engine to the shared Elasticsearch instance/cluster and Optimize #2 only accesses the engine in order to authenticate and authorize users.

On this Page: