Configuration and Helm Values

This page describes how to configure Cadenza for deployment on Kubernetes using Helm values. Before you can install Cadenza, you need to prepare a custom-values.yaml file that contains your installation-specific configuration.

The configuration process includes:

Accessing the Helm chart and container images from the Disy registry
Preparing Helm values for your specific deployment needs
Configuring Kubernetes-specific settings for PDF export and message broker
Defining resource requirements for production deployments

Accessing Container Images and Helm Chart

The Cadenza Helm chart and all required container images are available on the External Disy registry.

You need credentials (username and password) to pull the Cadenza images and Helm chart from the Disy registry. Please contact your account representative to receive these credentials.

Accessing the Helm Chart

First, authenticate with the Disy registry:

helm registry login registry-ext.disy.net --username <your-username>

You will be prompted to enter your password interactively.

You can either pull the chart for local inspection or directly install it. To pull the chart locally:

helm pull oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x

Alternatively, you can install the chart directly without pulling it first (see Installation and Updates).

Creating a Pull Secret for the Disy Registry

When installing the Helm chart in your Kubernetes cluster, the cluster needs to authenticate with the Disy registry to pull the container images. For this, you must create a pull secret in the namespace where Cadenza will be deployed.

Create the pull secret using the same credentials you received for the Helm registry access:

kubectl create secret docker-registry disy-registry-secret \
  --docker-server=registry-ext.disy.net \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  -n my-namespace

The pull secret must exist in the same namespace as your Cadenza deployment.

You will need to reference this pull secret name (e.g. disy-registry-secret) in your custom-values.yaml file when configuring the Helm chart installation. Refer to the Helm chart documentation for details on how to configure the pull secret in your values file. Please also adjust my-namespace to your needs.

Preparing Helm Values

Before deploying Cadenza, you need to prepare a values file (e.g. custom-values.yaml) that contains your installation-specific configuration.

For production deployments, we strongly recommend using PostgreSQL as the database system. Complete all necessary preparations before creating your Helm values file. Refer to Overview of the Necessary Preparations for detailed instructions.

The Helm chart documentation provides a comprehensive README with configuration examples, a complete overview of all available Helm values with descriptions, and a diff view to compare default values between chart versions.

To create your initial custom-values.yaml file, you can export the default values using Helm:

helm show values oci://registry-ext.disy.net/cadenza-helm/cadenza \
  --version 10.4.x > custom-values.yaml

Then edit this file to match your specific requirements, including database connection settings, pull secret reference for the Disy registry, resource limits and requests, and Ingress configuration. You should delete all non-modified lines (preserving the correct YAML syntax) in order to make updates easier - you do only have to check if one of your modifications has changed in a new chart version instead of looking through the whole file and without knowing which of the lines have been changed from the default ones.

Store your custom-values.yaml file in a version control system like Git. This allows you to track changes, revert modifications if necessary, and reuse the file for future deployment updates.

Configuring Cadenza via Helm Values

The Helm chart includes Cadenza’s application configuration under the Helm value cadenza.config.configuration. This configuration follows the single-file configuration format described in Single-file Configuration Mode.

When mapping from a standalone single-file configuration to Helm values, the root key cadenzaconfig is replaced by the Helm value path cadenza.config.configuration. For example:

In a single-file configuration file: cadenzaconfig.plugins
In Helm values: cadenza.config.configuration.plugins

The content and structure of the cadenza.config.configuration section corresponds exactly to what is documented in Configuration Files for single-file configuration.

This allows you to configure all aspects of Cadenza (plugins, databases, repositories, etc.) directly in your custom-values.yaml file using standard Helm practices.

The default Helm values already include a functional Cadenza configuration in cadenza.config.configuration. When customizing this configuration in your custom-values.yaml file, be aware of Helm’s merge behavior: Helm merges your custom values with the default values. Depending on the structure, this may result in different outcomes:

YAML maps (objects): Values are recursively merged. Custom values are combined with default values.
YAML lists (arrays): Lists are replaced entirely, not merged. If you override a list in your custom values, the entire default list is discarded.

Review the default values carefully and understand how Helm merges YAML structures to ensure your configuration produces the expected result.

The Cadenza Helm chart manages all environment variables and system properties documented in Environment Variables and System Properties. Where appropriate, these variables are wrapped in dedicated Helm values for easier configuration. Other environment variables are managed entirely by the chart itself. You should not directly set or modify any of these environment variables in your custom Helm values.

Specifying the Cadenza Version

We strongly recommend specifying a concrete patch version for the Cadenza image instead of using only the major version. The Helm chart defaults to the major version as the image tag because the chart has a different release cycle than Cadenza patch releases. To use a specific patch version, set the following in your custom-values.yaml:

cadenza:
  image:
    tag: "10.4.x-release"

This ensures you deploy a specific, tested version of Cadenza rather than relying on a moving major version tag. Contact your Disy account representative to obtain the recommended patch version x for your deployment.

Kubernetes-Specific Configuration Requirements

When running Cadenza on Kubernetes, certain configuration aspects require special attention:

PDF Export (Workbook Reporting): Configuration of the remote WebDriver for report generation
Message Broker: Configuration of Cadenza’s internal messaging cluster for multi-node operation

PDF Export Configuration

For PDF export functionality, Cadenza needs to communicate with a headless browser (Chromedriver). The default Helm values already include the configuration section cadenza.config.configuration.settings.workbookreport with a remoteWebDriverUrl.

You must ensure that:

WebDriver Service URL: The cadenza.config.configuration.settings.workbookreport.remoteWebDriverUrl must point to the Kubernetes Service name of the WebDriver deployment.
Public URL: The cadenza.config.configuration.settings.workbookreport.publicUrl must point to the Ingress host - the external URL where Cadenza is accessible. This URL must point exactly to the Cadenza context, which is /cadenza by default.

Example configuration:

cadenza:
  config:
    configuration:
      settings:
        workbookreport:
          remoteWebDriverUrl: "http://cadenza-chromedriver:4444"
          publicUrl: "https://my-cadenza.example.com/cadenza"

In this example:

remoteWebDriverUrl points to the internal Kubernetes Service (adjust to your actual service name if different)
publicUrl is set to https://my-cadenza.example.com/cadenza (adjust to your actual Ingress host and context path)

Message Broker Configuration

When running Cadenza with more than one replica (multi-node operation), you must configure the message broker for cluster communication. See Cluster Requirements for general requirements and Cluster Messaging Configuration for detailed configuration instructions.

For Kubernetes deployments, configure the message broker to use Kubernetes service discovery. You must specify the Kubernetes Service name and Deployment name for Cadenza:

Example configuration:

cadenza:
  config:
    configuration:
      messagebroker:
        messageBrokerDiscoveryPort: "47500"
        messageBrokerCommunicationPort: "47100"
        kubernetesDiscovery:
          serviceName: "my-cadenza-service"
          deploymentName: "my-cadenza"

Where:

serviceName: Name of the Kubernetes Service for Cadenza
deploymentName: Name of the Kubernetes Deployment for Cadenza

The actual service and deployment names depend on your Helm release name and chart configuration. Check your cluster or review the Helm chart templates for the correct names.

Cadenza’s internal messaging cluster requires an odd number of replicas at all times to properly determine cluster majority. You must not scale the Cadenza deployment to an even number of replicas using native Kubernetes scaling mechanisms (e.g., kubectl scale or HorizontalPodAutoscaler). Always maintain an odd number of replicas (1, 3, 5, 7, etc.).

Resource Requirements

The Cadenza Helm chart includes default resource requests and limits for all components. These defaults provide a baseline for development and testing environments. For production deployments, you should adjust these values based on your expected workload.

Default Resource Allocations

The following table shows the default resource allocations defined in the Helm chart:

Component	Requests	Limits
Cadenza	CPU: 250m, Memory: 2Gi	CPU: 2, Memory: 2Gi
Webdriver (Chromedriver)	CPU: 1, Memory: 1Gi	CPU: 1, Memory: 1Gi
Database Migration Tool	CPU: 500m, Memory: 2Gi	CPU: 1, Memory: 2Gi
Fluent Bit (if enabled)	CPU: 100m, Memory: 128Mi	CPU: 100m, Memory: 128Mi

Component

Requests

Limits

Cadenza

CPU: 250m, Memory: 2Gi

CPU: 2, Memory: 2Gi

Webdriver (Chromedriver)

CPU: 1, Memory: 1Gi

Database Migration Tool

CPU: 500m, Memory: 2Gi

CPU: 1, Memory: 2Gi

Fluent Bit (if enabled)

CPU: 100m, Memory: 128Mi

Production Recommendations

For production deployments, consider the following recommendations based on the Server Requirements:

Cadenza Main Application (per replica):

Minimum production configuration:
- requests: cpu: 1, memory: 2Gi
- limits: cpu: 2, memory: 2Gi
Recommended production configuration:
- requests: cpu: 1, memory: 4Gi
- limits: cpu: 4, memory: 4Gi
Resource-intensive workloads (complex analyses, many concurrent users):
- requests: cpu: 2, memory: 8Gi
- limits: cpu: 6, memory: 8Gi

Memory requests and limits must always be set to the same value to ensure quality of service (QoS class "Guaranteed"). This prevents the pod from being evicted under memory pressure and it prevents killing the Java process since Java cannot deal with a reduction of its memory during the lifetime of a pod.

Example custom-values.yaml for production:

cadenza:
  replicas: 3
  resources:
    requests:
      cpu: "1"
      memory: 4Gi
    limits:
      cpu: "4"
      memory: 4Gi

  webdriver:
    resources:
      requests:
        cpu: "1"
        memory: 1Gi
      limits:
        cpu: "2"
        memory: 1Gi

CPU requests determine the guaranteed CPU time allocated to the container. CPU limits allow bursting beyond the requested amount when available. For Cadenza, a lower CPU request with higher limits allows efficient resource sharing while maintaining performance during peak loads.

Sizing Considerations

When determining the appropriate resource allocations for your deployment:

Number of concurrent users: More concurrent users require more memory and CPU per replica
Repository complexity: Complex maps, large datasets, and extensive analysis require additional resources
Report generation frequency: Frequent PDF report generation increases CPU and Webdriver usage
Multi-node deployments: Production deployments typically use 3 replicas for high availability. Each replica requires the full resource allocation.

For example, a production deployment with 3 Cadenza replicas configured with 4Gi memory each requires a total of 12Gi memory across the cluster (plus additional resources for Webdriver and other components).

Remember that Cadenza’s internal messaging cluster requires an odd number of replicas (1, 3, 5, 7, etc.) as documented in the Cluster Requirements.