Configuration

Tasklist is a Spring Boot application. This means all provided ways to configure a Spring Boot application can be applied.

By default, the configuration for Tasklist is stored in a YAML file application.yml. All Tasklist-related settings are prefixed with camunda.tasklist. The following components are configurable:

• Webserver
• GraphQL API access
• Elasticsearch connection
• Zeebe Broker connection
• Zeebe Elasticsearch exporter
• Authentication
• Monitoring and health probes
• Logging configuration

Webserver

Tasklist supports customizing the context-path using the default Spring configuration.

Example for application.yml: server.servlet.context-path: /tasklist

Example for environment variable: SERVER_SERVLET_CONTEXT_PATH=/tasklist

Default context-path is /.

GraphQL API access

Tasklist provides a GraphQL API under the endpoint /graphql. Clients can access this API using a JWT access token in an authorization header Authorization: Bearer <JWT>.

The Tasklist server requires the following settings to validate the token:

Setting	Description	Example
camunda.tasklist.client.audience	Tasklist tries to match this with aud in JWT.	tasklist.camunda.io
camunda.tasklist.client.clusterId	Tasklist tries to match this with scope in JWT.	cafe-0815-0235-a221-21cc6df91dc5
spring.security.oauth2.resourceserver.jwt.jwk-set-uri (recommended)	Complete URI to get public keys for JWT validation.	https://weblogin.cloud.company.com/.well-known/jwks.json
OR
spring.security.oauth2.resourceserver.jwt.issuer-uri	URI to get public keys for JWT validation.	https://weblogin.cloud.company.com/

The settings can be given in application.yml (eg. camunda.tasklist.client.audience: tasklist.camunda.io) or as environment variables (eg. CAMUNDA_TASKLIST_CLIENT_AUDIENCE=tasklist.camunda.io).

The API client must obtain the JWT token and send it in each request to graphql in an authorization header as described above.

Elasticsearch

Tasklist stores and reads data in/from Elasticsearch.

Settings to connect

Tasklist supports basic authentication for Elasticsearch. Set the appropriate username/password combination in the configuration to use it.

Settings to connect to a secured Elasticsearch instance

To connect to a secured (https) Elasticsearch instance you need normally only set the URL protocol part to https instead of http. A secured Elasticsearch instance needs also username and password. The other SSL settings should only be used in case of connection problems, for example disable host verification.

note

You may need to import the certificate into JVM runtime.

Name	Description	Default value
camunda.tasklist.elasticsearch.indexPrefix	Prefix for index names	tasklist
camunda.tasklist.elasticsearch.clusterName	Clustername of Elasticsearch	elasticsearch
camunda.tasklist.elasticsearch.url	URL of Elasticsearch REST API	http://localhost:9200
camunda.tasklist.elasticsearch.username	Username to access Elasticsearch REST API	-
camunda.tasklist.elasticsearch.password	Password to access Elasticsearch REST API	-
camunda.tasklist.elasticsearch.ssl.certificatePath	Path to certificate used by Elasticsearch	-
camunda.tasklist.elasticsearch.ssl.selfSigned	Certificate was self signed	false
camunda.tasklist.elasticsearch.ssl.verifyHostname	Should the hostname be validated	false

Settings for shards and replicas

Tasklist creates the template with index settings named tasklist-<version>_template that Elasticsearch uses for all Tasklist indices. These settings can be changed.

The following configuration parameters define the settings:

Name	Description	Default value
camunda.tasklist.elasticsearch.numberOfShards	How many shards Elasticsearch uses for all Tasklist indices.	1
camunda.tasklist.elasticsearch.numberOfReplicas	How many replicas Elasticsearch uses for all Tasklist indices.	0

These values are applied only on first startup of Tasklist or during version upgrade. After the Tasklist ELS schema is created, settings may be adjusted directly in the ELS template, and the new settings are applied to indices created after adjustment.

A snippet from application.yml

camunda.tasklist:
  elasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # Url
    url: https://localhost:9200
    ssl:
      selfSigned: true

Zeebe broker connection

Tasklist needs a connection to Zeebe broker to start the import.

Settings to connect

Name	Description	Default value
camunda.tasklist.zeebe.gatewayAddress	Gateway address point to Zeebe as hostname and port.	localhost:26500

note

Currently, Tasklist does not support TLS communication with Zeebe.

A snippet from application.yml

camunda.tasklist:
  zeebe:
    # Gateway address
    gatewayAddress: localhost:26500

Zeebe Elasticsearch exporter

Tasklist imports data from Elasticsearch indices created and filled in by Zeebe Elasticsearch Exporter.

Therefore, settings for this Elasticsearch connection must be defined and correspond to the settings on the Zeebe side.

Settings to connect and import

See also settings to connect to a secured Elasticsearch instance.

Name	Description	Default value
camunda.tasklist.zeebeElasticsearch.clusterName	Cluster name of Elasticsearch	elasticsearch
camunda.tasklist.zeebeElasticsearch.url	URL of Elasticsearch REST API	http://localhost:9200
camunda.tasklist.zeebeElasticsearch.prefix	Index prefix as configured in Zeebe Elasticsearch exporter	zeebe-record
camunda.tasklist.zeebeElasticsearch.username	Username to access Elasticsearch REST API	-
camunda.tasklist.zeebeElasticsearch.password	Password to access Elasticsearch REST API	-
camunda.tasklist.zeebeElasticsearch.ssl.certificatePath	Path to certificate used by Elasticsearch	-
camunda.tasklist.zeebeElasticsearch.ssl.selfSigned	Certificate was self signed	false
camunda.tasklist.zeebeElasticsearch.ssl.verifyHostname	Should the hostname be validated	false

A snippet from application.yml

camunda.tasklist:
  zeebeElasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # Url
    url: https://localhost:9200
    # Index prefix, configured in Zeebe Elasticsearch exporter
    prefix: zeebe-record

Monitoring and health probes

Tasklist includes the Spring Boot Actuator inside, which provides the number of monitoring possibilities (e.g. health check (http://localhost:8080/actuator/health) and metrics (http://localhost:8080/actuator/prometheus) endpoints).

Tasklist uses the following Actuator configuration by default:

# disable default health indicators:
# https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-health-indicators
management.health.defaults.enabled: false
# enable health check, metrics and loggers endpoints
management.endpoints.web.exposure.include: health,prometheus,loggers
# enable Kubernetes health groups:
# https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-kubernetes-probes
management.health.probes.enabled: true

With this configuration, the following endpoints are available for use out of the box:

<server>:8080/actuator/prometheus Prometheus metrics

<server>:8080/actuator/health/liveness Liveness probe

<server>:8080/actuator/health/readiness Readiness probe

Example snippets to use Tasklist probes in Kubernetes

For details to set Kubernetes probes parameters, see Kubernetes configure probes.

Readiness probe as yaml config

readinessProbe:
     httpGet:
        path: /actuator/health/readiness
        port: 8080
     initialDelaySeconds: 30
     periodSeconds: 30

Liveness probe as yaml config

livenessProbe:
     httpGet:
        path: /actuator/health/liveness
        port: 8080
     initialDelaySeconds: 30
     periodSeconds: 30

Logging

Tasklist uses Log4j2 framework for logging. In the distribution archive and inside a Docker image config/log4j2.xml, logging configuration files are included and can be further adjusted to your needs:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">
  <Properties>
    <Property name="LOG_PATTERN">%clr{%d{yyyy-MM-dd HH:mm:ss.SSS}}{faint} %clr{%5p} %clr{${sys:PID}}{magenta} %clr{---}{faint} %clr{[%15.15t]}{faint} %clr{%-40.40c{1.}}{cyan} %clr{:}{faint} %m%n%xwEx</Property>
    <Property name="log.stackdriver.serviceName">${env:TASKLIST_LOG_STACKDRIVER_SERVICENAME:-tasklist}</Property>
    <Property name="log.stackdriver.serviceVersion">${env:TASKLIST_LOG_STACKDRIVER_SERVICEVERSION:-}</Property>
  </Properties>
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT" follow="true">
      <PatternLayout pattern="${LOG_PATTERN}"/>
    </Console>
    <Console name="Stackdriver" target="SYSTEM_OUT" follow="true">
      <StackdriverLayout serviceName="${log.stackdriver.serviceName}"
        serviceVersion="${log.stackdriver.serviceVersion}" />
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="io.camunda.tasklist" level="info" />
    <Root level="info">
      <AppenderRef ref="${env:TASKLIST_LOG_APPENDER:-Console}"/>
    </Root>
  </Loggers>
</Configuration>

By default, Console Appender is used.

JSON logging configuration

You can choose to output logs in JSON format (Stackdriver compatible). To enable it, define the environment variable TASKLIST_LOG_APPENDER like the following:

TASKLIST_LOG_APPENDER=Stackdriver

Change logging level at runtime

Tasklist supports the default scheme for changing logging levels as provided by Spring Boot.

The log level for Tasklist can be changed by following the Setting a Log Level section.

Set all Tasklist loggers to DEBUG

curl 'http://localhost:8080/actuator/loggers/io.camunda.tasklist' -i -X POST \
-H 'Content-Type: application/json' \
-d '{"configuredLevel":"debug"}'

An example of application.yml file

The following snippet represents the default Tasklist configuration, which is shipped with the distribution. It can be found inside the config folder (config/application.yml) and can be used to adjust Tasklist to your needs.

# Tasklist configuration file

camunda.tasklist:
  # Set Tasklist username and password.
  # If user with <username> does not exists it will be created.
  # Default: demo/demo
  #username:
  #password:
  #roles:
  #  - OWNER
  #  - OPERATOR
  
  # ELS instance to store Tasklist data
  elasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # url
    url: http://localhost:9200
  # Zeebe instance
  zeebe:
    # Gateway address
    gatewayAddress: localhost:26500
  # ELS instance to export Zeebe data to
  zeebeElasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # url
    url: http://localhost:9200
    # Index prefix, configured in Zeebe Elasticsearch exporter
    prefix: zeebe-record