Helm Secret Management Changes in Camunda 8.9

If you run Camunda 8 Self-Managed on Kubernetes using our official Helm chart, there are important changes coming to how secrets are configured.

We introduced a new, standardized secret management pattern in Camunda 8.8 and marked the old legacy parameters as deprecated. In Camunda 8.9, we will complete this transition by removing support for the legacy secret parameters and enforce only the new pattern.

This post is for you if:

• You manage values.yaml for Camunda’s Helm chart.
• You rely on existingSecret/legacy secret settings today.
• You may have missed the earlier documentation announcement about this change.

We’ll recap what changed in 8.8, what is changing in 8.9, and why we’re doing this.

How Helm secret management works today

The secret management guide in our documentation describes how the Helm chart handles internal and external secrets, including license keys, OAuth client secrets, database passwords, document store credentials, and more.

From Camunda 8.8 onward, the chart supports a new, structured secret block per component, with three clear options:

component:
  auth:
    secret:
      inlineSecret: "my-plain-text-secret"  # Non-production only
      existingSecret: "my-secret-name"      # Recommended for production
      existingSecretKey: "secret-key"

• inlineSecret: A plaintext value in values.yaml for nonproduction only
• existingSecret: A Kubernetes Secret containing the value; recommended in production
• existingSecretKey: The specific key inside that Kubernetes Secret

This structured pattern is used across many internal and external secrets in 8.8+, including Identity OAuth clients, Optimize, Connectors, Orchestration, and Document Store.

For Camunda 8.7 and earlier, we used several legacy fields, often based on existingSecret in inconsistent formats: sometimes as a plain string password, other times as a secret name plus separate key parameters. We set out to eliminate this inconsistency.

What changed in Camunda 8.8

In 8.8, we delivered a unified secret configuration pattern and a transition layer so that you could adopt it without breaking changes.

New unified secret structure

The chart now uses <something>.secret.inlineSecret / existingSecret / existingSecretKey consistently for non-subchart secrets. For example:

• global.license.secret.*
• identity.firstUser.secret.*
• global.identity.auth.*.secret.* for various OAuth clients
• webModeler.restapi.externalDatabase.secret.*
• global.opensearch.auth.secret.*, etc.

Backward-compatible normalizer for legacy values

To ensure 8.8 is non-breaking, we introduced logic that:

• Uses the new secret.* values when set.
• Falls back to deprecated legacy keys if the new ones are not set.
• Emits warnings when a plaintext password is used as a string, to signal that this is not recommended for production.

Deprecation markers and constraints

To enable 8.8 customers to have visibility into the upcoming changes, we ensured that:

• All legacy secret parameters in values.yaml are marked as DEPRECATED, pointing you to the new secret.* equivalents.
• Helm schema constraints run at warning level:
  • If you continue to use legacy values, you see a warning encouraging you to migrate.
  • If you set both legacy and new values for the same secret, you see a warning explaining which one has priority.

Changes coming in Camunda 8.9

With Camunda 8.9, we complete the migration and remove the legacy configuration surface.

• A set of 36 deprecated secret parameters are planned for removal in 8.9. They currently exist only as fallback options in the chart templates.
• The constraints that were warnings in 8.8 become errors in 8.9.

Combined, this means that if you do not update your legacy secrets, your upgrade to 8.9 is blocked until you migrate to the new pattern.

Why we’re making this change

This change benefits your organization, your administrators, and your Helm chart managers with:

• More explicit configuration. The new pattern requires you to specify both existingSecret and existingSecretKey where applicable. There are no hidden default key names which reduces surprises when switching clusters, regenerating secrets, or rotating credentials.
• Fewer “black box” behaviors. In some cases, the legacy approach relied on hard-coded default keys and implicit behavior when certain fields were omitted. With the new pattern, it’s clear which Kubernetes Secret and which key are used for each credential.
• Consistent pattern across components. Previously, components used different shapes of the existingSecret (string, map, name + key, etc.) pattern. Now there’s one consistent structure across internal secrets, external databases, and cloud storage credentials, making Helm values easier to read, reason about, and review.
• Easier reviews and audits. Because the values are explicit and consistent, it’s simpler to review a values file, verify what’s stored where, and ensure secrets aren’t accidentally left inline in production.

Overall, this makes the chart easier to maintain and evolve, and helps us deliver improvements faster with fewer surprises.

For more information please refer to the documentation or contact us.