Skip to content

Commit deed2ed

Browse files
hisImminencehisImminence
authored
Merge pull request #8097 from camunda/update-configure-application-configuration
fix: update component page to highlight extraConfiguration
2 parents 2c4ee21 + 86957f4 commit deed2ed

File tree

3 files changed

+258
-42
lines changed

3 files changed

+258
-42
lines changed

‎docs/reference/announcements-release-notes/890/890-announcements.md‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,46 @@ To learn more, see the [8.9.0-alpha1 release notes](/reference/announcements-rel
333333
</div>
334334
<div className="release-announcement-content">
335335

336+
#### Helm chart: `extraConfiguration` format changed from map to ordered list
337+
338+
The `<componentName>.extraConfiguration` Helm value has changed from a **map** (key-value pairs) to an **ordered list** of `file`/`content` entries. This ensures configuration entries are always applied in the order you define them, since maps in Go templates do not guarantee iteration order.
339+
340+
The old map format is **not supported** in Camunda 8.9. If you upgrade without converting to the new list format, Helm will fail during template rendering.
341+
342+
**Before (8.8 — map):**
343+
344+
```yaml
345+
identity:
346+
extraConfiguration:
347+
custom-logging.yaml: |
348+
logging:
349+
level:
350+
ROOT: DEBUG
351+
```
352+
353+
**After (8.9 — ordered list):**
354+
355+
```yaml
356+
identity:
357+
extraConfiguration:
358+
- file: custom-logging.yaml
359+
content: |
360+
logging:
361+
level:
362+
ROOT: DEBUG
363+
```
364+
365+
See [Migrate extraConfiguration from 8.8 to 8.9](/self-managed/deployment/helm/configure/application-configs.md#migrate-extraconfiguration-from-88-to-89) for detailed migration steps.
366+
367+
</div>
368+
</div>
369+
370+
<div className="release-announcement-row">
371+
<div className="release-announcement-badge">
372+
<span className="badge badge--breaking-change">Breaking change</span>
373+
</div>
374+
<div className="release-announcement-content">
375+
336376
#### Elasticsearch subchart no longer enabled by default
337377
338378
Previously, the Elasticsearch subchart was enabled by default. To use OpenSearch, you would need to disable Elasticsearch and enable OpenSearch.
@@ -512,7 +552,7 @@ To learn more, see the [8.9.0-alpha2 release notes](/reference/announcements-rel
512552

513553
Camunda 8.9 adds support for H2, MariaDB, and MySQL as relational databases for Web Modeler.
514554

515-
This enhancement aligns Web Modeler’s database configuration with the Orchestration cluster, ensuring consistent setup and improved integration across environments.
555+
This enhancement aligns Web Modeler's database configuration with the Orchestration cluster, ensuring consistent setup and improved integration across environments.
516556

517557
:::info
518558
To learn more, see the [8.9.0-alpha1 release notes](/reference/announcements-release-notes/890/890-release-notes.md#web-modeler-rdbms-support-h2-mariadb-mysql).

‎docs/self-managed/deployment/helm/configure/application-configs.md‎

Lines changed: 211 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
---
22
id: application-configs
3-
sidebar_label: Components
4-
title: Configure Helm chart components
3+
sidebar_label: Configure component configuration
4+
title: Configure component configuration
55
description: "Learn how to configure individual Camunda components in Helm charts."
66
---
77

8-
This page explains how to configure Camunda components in Helm charts. You can define options in `values.yaml` and provide custom files for additional configuration.
8+
This page explains how to configure Camunda components in Helm charts.
9+
10+
For most use cases, use `<componentName>.extraConfiguration` to add or override properties while keeping the chart-provided defaults. Use `<componentName>.configuration` only when you intentionally want to replace the entire default application configuration file.
11+
12+
For the complete list of configuration options per component, see the [Self-Managed Components documentation](../../../components/orchestration-cluster/overview.md) (this is where each component documents its supported application configuration).
913

1014
## Prerequisites
1115

@@ -17,22 +21,70 @@ This page explains how to configure Camunda components in Helm charts. You can d
1721

1822
### Parameters
1923

20-
| Key | Type | Description |
21-
| ------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22-
| `<componentName>.configuration` | string | Full application configuration content (for example, the contents of `application.yaml`). |
23-
| `<componentName>.extraConfiguration` | list | Additional configuration entries. Each entry has a `file` (filename) and `content` (file contents). Behavior depends on the component — see [how it works per component](#how-extraConfiguration-works-per-component). |
24+
| Key | Type | Description |
25+
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26+
| `<componentName>.extraConfiguration` | list | **Recommended:** Additional configuration entries layered on top of the default configuration. Each entry has a `file` (filename) and `content` (file contents). See [how it works per component](#how-extraconfiguration-works-per-component). |
27+
| `<componentName>.configuration` | string | **Advanced:** Full application configuration file content (for example, the full contents of `application.yaml`). Using this **replaces** the component's default application configuration. |
2428

2529
### Configuration options
2630

2731
Two Helm values are available for component configuration:
2832

29-
- `<componentName>.configuration`
3033
- `<componentName>.extraConfiguration`
34+
- `<componentName>.configuration`
35+
36+
:::tip Which should I use?
37+
38+
- Use `<componentName>.extraConfiguration`. It keeps the chart-provided defaults intact and lets you add/override only the keys you need.
39+
- Use `<componentName>.configuration` only if you intentionally want to take full control of the application's configuration file. It **overwrites** the default config and can affect startup behavior and upgrades.
40+
:::
41+
42+
#### componentName.extraConfiguration
43+
44+
Use `<componentName>.extraConfiguration` to add or override configuration **without replacing** the component's default configuration. This option accepts an **ordered list** of entries, where each entry specifies a `file` name and its `content`. Entries are processed in order, so **later entries override earlier ones** for duplicate keys — mimicking Spring Boot's `spring.config.import` semantics.
45+
46+
:::info Recommended default
47+
Start with `<componentName>.extraConfiguration` whenever possible. It is safer for upgrades because the Helm chart can continue to evolve its defaults while you only maintain the deltas you actually care about.
48+
:::
49+
50+
```yaml
51+
identity:
52+
extraConfiguration:
53+
- file: logging-debug.yaml
54+
content: |
55+
logging:
56+
level:
57+
ROOT: DEBUG
58+
io.camunda.identity: DEBUG
59+
- file: logging-production.yaml
60+
content: |
61+
logging:
62+
level:
63+
ROOT: INFO
64+
io.camunda.identity: INFO
65+
```
66+
67+
In this example, `logging-production.yaml` is applied after `logging-debug.yaml`, so the final effective log level is `INFO` (last writer wins).
68+
69+
:::note Why an ordered list?
70+
Previous versions of the Helm chart used a map (key-value pairs) for `extraConfiguration`. Maps in Go (and Helm) do not guarantee iteration order. Since configuration layering is order-dependent, `extraConfiguration` now uses an array to ensure entries are always applied in the order you define them.
71+
:::
3172

3273
#### componentName.configuration
3374

3475
Use `<componentName>.configuration` to define an application configuration file directly in `values.yaml`.
3576

77+
:::caution Advanced option (overwrites defaults)
78+
When you set `<componentName>.configuration`, the Helm chart renders **your content as the entire application configuration file** for that component.
79+
80+
This means:
81+
82+
- You are responsible for including any settings that the chart normally provides by default.
83+
- During upgrades, configuration format or default changes may require you to update your configuration before the component can start.
84+
85+
Prefer `<componentName>.extraConfiguration` unless you specifically need to replace the full file.
86+
:::
87+
3688
For example, `application.yaml`:
3789

3890
```yaml
@@ -60,36 +112,14 @@ orchestration:
60112
number-of-replicas: "1"
61113
```
62114

63-
#### componentName.extraConfiguration
64-
65-
Use `<componentName>.extraConfiguration` to provide additional configuration overrides. This option accepts an **ordered list** of entries, where each entry specifies a `file` name and its `content`. Entries are processed in order, so **later entries override earlier ones** for duplicate keys — mimicking Spring Boot's `spring.config.import` semantics.
66-
67-
```yaml
68-
identity:
69-
extraConfiguration:
70-
- file: logging-debug.yaml
71-
content: |
72-
logging:
73-
level:
74-
ROOT: DEBUG
75-
io.camunda.identity: DEBUG
76-
- file: logging-production.yaml
77-
content: |
78-
logging:
79-
level:
80-
ROOT: INFO
81-
io.camunda.identity: INFO
82-
```
83-
84-
In this example, `logging-production.yaml` is applied after `logging-debug.yaml`, so the final effective log level is `INFO` (last writer wins).
115+
### Default properties
85116

86-
:::note Why an ordered list?
87-
Previous versions of the Helm chart used a map (key-value pairs) for `extraConfiguration`. Maps in Go (and Helm) do not guarantee iteration order. Since configuration layering is order-dependent, `extraConfiguration` now uses an array to ensure entries are always applied in the order you define them.
88-
:::
117+
The `helm template` command can show you the application's default configuration as rendered by the chart.
89118

90-
### Default properties
119+
- Use this output as a **reference** to discover the right keys and defaults.
120+
- Only copy the full content into `<componentName>.configuration` if you intentionally want to **replace** the default config (advanced).
91121

92-
The `helm template` command generates the application's default configuration. Keep the original `values.yaml` unchanged and maintain a separate file with your custom settings. For details, see [Creating your own values files](self-managed/deployment/helm/chart-parameters.md#creating-your-own-values-files). To generate the default configuration, replace `<your-release-name>` with your release name and run:
122+
Keep the original `values.yaml` unchanged and maintain a separate file with your custom settings. For details, see [Creating your own values files](self-managed/deployment/helm/chart-parameters.md#creating-your-own-values-files). To generate the default configuration, replace `<your-release-name>` with your release name and run:
93123

94124
```bash
95125
helm template <your-release-name> \
@@ -98,7 +128,10 @@ helm template <your-release-name> \
98128
--show-only templates/operate/configmap.yaml
99129
```
100130

101-
The `--show-only` flag prints the `configmap`. Copy the `application.yml` content and place it under the appropriate `<component>.configuration` key in `values.yaml`.
131+
The `--show-only` flag prints the `configmap`.
132+
133+
- If you are using `<componentName>.extraConfiguration`, use the rendered `application.yml` to identify the correct keys and then add only the overrides you need.
134+
- If you are using `<componentName>.configuration`, copy the full `application.yml` content, modify it, and place it under the appropriate `<component>.configuration` key in `values.yaml`.
102135

103136
### How extraConfiguration works per component
104137

@@ -168,7 +201,7 @@ camunda:
168201
`console.overrideConfiguration` is the old way of overriding the default application configuration for Console. It has been deprecated. Please convert to using `console.extraConfiguration`.
169202
:::
170203

171-
#### Customer Configuration Loading
204+
#### Custom configuration loading
172205

173206
**Applies to:** Optimize
174207

@@ -393,7 +426,35 @@ zeebe:
393426

394427
### Step 5: Add the configuration to `values.yaml`
395428

396-
Finally, place the updated configuration under `zeebe.configuration` in `values.yaml`:
429+
Prefer adding the new settings via `zeebe.extraConfiguration` so you only maintain the keys you changed and keep the chart-provided defaults.
430+
431+
For example:
432+
433+
```yaml
434+
zeebe:
435+
extraConfiguration:
436+
- file: backup-s3.yaml
437+
content: |-
438+
zeebe:
439+
broker:
440+
data:
441+
backup:
442+
store: "S3"
443+
s3:
444+
bucketName: "zeebebackuptest"
445+
region: "us-east-1"
446+
endpoint: "http://loki-minio.monitoring.svc.cluster.local:9000"
447+
accessKey: "supersecretaccesskey"
448+
secretKey: "supersecretkey"
449+
apiCallTimeout: "PT180S"
450+
basePath: "zeebebackup"
451+
```
452+
453+
:::caution Advanced alternative: `zeebe.configuration` overwrites defaults
454+
If you intentionally want to fully control Zeebe's `application.yml`, place the full configuration under `zeebe.configuration`.
455+
456+
This replaces the chart's default configuration and may require updates during upgrades.
457+
:::
397458

398459
```yaml
399460
zeebe:
@@ -424,7 +485,6 @@ zeebe:
424485
# - technicalProcess
425486
# variableNameInclusionStartWith:
426487
# - businessTotal
427-
prefix: "zeebe-record"
428488
gateway:
429489
enable: true
430490
network:
@@ -511,16 +571,126 @@ Here, the bucket name is set twice. The environment variable `zeebetest1` overri
511571

512572
### Limitations
513573

514-
Customizing the `configuration` option will replace the entire contents of the configuration file. During upgrades, if the `configuration` option remains and if there are any application-level breaking changes to the configuration file format, this may cause the application component to crash.
574+
Setting the `configuration` option replaces the entire contents of the application's configuration file. During upgrades, if the `configuration` option remains and there are breaking changes to the configuration file format or required defaults, this can prevent the component from starting.
515575

516-
- The `configuration` option replaces the entire configuration file. During upgrades, if the file format changes, the component may fail to start until the configuration is updated.
576+
- Use `extraConfiguration` by default so you only maintain a small set of overrides.
577+
- The `configuration` option is an advanced override: if the file format or defaults change, the component may fail to start until you update your full configuration.
517578
- Forgetting to wrap multiline values with (`|`) in Helm can cause parse errors.
518579
- Mixing `env` and `configuration` for the same property without realizing precedence can lead to unexpected results.
519580

581+
## Migrate extraConfiguration from 8.8 to 8.9
582+
583+
In Camunda 8.8 and earlier, `<componentName>.extraConfiguration` was a **map** where each key was a filename and each value was the file content:
584+
585+
```yaml
586+
# 8.8 format (map)
587+
identity:
588+
extraConfiguration:
589+
custom-logging.yaml: |
590+
logging:
591+
level:
592+
ROOT: DEBUG
593+
io.camunda.identity: DEBUG
594+
custom-cache.yaml: |
595+
spring:
596+
cache:
597+
type: caffeine
598+
```
599+
600+
Starting with Camunda 8.9, `<componentName>.extraConfiguration` is an **ordered list** of entries, where each entry has a `file` (filename) and `content` (file contents):
601+
602+
```yaml
603+
# 8.9 format (ordered list)
604+
identity:
605+
extraConfiguration:
606+
- file: custom-logging.yaml
607+
content: |
608+
logging:
609+
level:
610+
ROOT: DEBUG
611+
io.camunda.identity: DEBUG
612+
- file: custom-cache.yaml
613+
content: |
614+
spring:
615+
cache:
616+
type: caffeine
617+
```
618+
619+
### Why this changed
620+
621+
Maps in Go templates (used by Helm) do not guarantee iteration order. Since configuration layering is order-dependent — later entries override earlier ones for the same keys — the map format could produce unpredictable results. The ordered list format ensures entries are always applied in the sequence you define them.
622+
623+
### Migration steps
624+
625+
For every component where you use `extraConfiguration`, convert each map entry to a list entry:
626+
627+
1. **Identify all components** in your `values.yaml` that use `extraConfiguration` (for example, `identity`, `orchestration`, `connectors`, `optimize`, `console`, `webModeler`).
628+
629+
2. **Convert each map entry to a list entry.** For every key-value pair in the old map, create a list item with `file:` set to the former key and `content:` set to the former value.
630+
631+
**Before (8.8):**
632+
633+
```yaml
634+
orchestration:
635+
extraConfiguration:
636+
backup-s3.yaml: |
637+
zeebe:
638+
broker:
639+
data:
640+
backup:
641+
store: "S3"
642+
s3:
643+
bucketName: "my-bucket"
644+
custom-threads.yaml: |
645+
zeebe:
646+
broker:
647+
threads:
648+
cpuThreadCount: "4"
649+
```
650+
651+
**After (8.9):**
652+
653+
```yaml
654+
orchestration:
655+
extraConfiguration:
656+
- file: backup-s3.yaml
657+
content: |
658+
zeebe:
659+
broker:
660+
data:
661+
backup:
662+
store: "S3"
663+
s3:
664+
bucketName: "my-bucket"
665+
- file: custom-threads.yaml
666+
content: |
667+
zeebe:
668+
broker:
669+
threads:
670+
cpuThreadCount: "4"
671+
```
672+
673+
3. **Order entries intentionally.** If two entries set the same configuration key, the **last entry in the list wins**. Arrange entries so that your highest-priority overrides appear last.
674+
675+
4. **Validate your configuration** before upgrading by running `helm template` with your updated values file and verifying the rendered ConfigMaps:
676+
677+
```bash
678+
helm template my-release camunda/camunda-platform \
679+
-f values-8.9.yaml \
680+
--show-only templates/orchestration/configmap.yaml
681+
```
682+
683+
5. **Proceed with the upgrade** using the updated values file. See the [8.8 to 8.9 upgrade guide](/self-managed/upgrade/helm/880-to-890.md) for additional steps.
684+
685+
:::caution
686+
The old map format is **not supported** in Camunda 8.9. If you upgrade without converting to the list format, Helm will fail during template rendering.
687+
:::
688+
520689
## References
521690

522691
For more details on where to find configuration options for specific components, see the following pages:
523692

693+
- [Components (Self-Managed)](../../../components/orchestration-cluster/overview.md)
524694
- [Zeebe Broker](/self-managed/components/orchestration-cluster/zeebe/configuration/broker.md)
525695
- [Zeebe Gateway](/self-managed/components/orchestration-cluster/zeebe/configuration/gateway.md)
526696
- [Operate](/self-managed/components/orchestration-cluster/operate/operate-configuration.md)

0 commit comments

Comments
 (0)