Skip to main content
Version: 8.8 (unreleased)

Helm charts secret management

This guide provides an overview for configuring and managing secrets when using the official Helm chart.

Secret configuration patterns

The Helm chart supports different patterns for secret management depending on your Camunda version:

Starting with Camunda 8.8, the new pattern uses a structured secret: configuration under components with three options:

  • inlineSecret: Plain-text value for non-production usage
  • existingSecret: Reference to an existing Kubernetes Secret name
  • existingSecretKey: Key within the existing secret object

Example:

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

Legacy pattern (Camunda 8.7 and below)

For Camunda 8.7 and earlier versions, the legacy pattern uses direct existingSecret and existingSecretKey fields. These are deprecated in 8.8+ but still supported for backward compatibility.

Bitnami subchart pattern

Some components use Bitnami subcharts for database services (PostgreSQL), which follow their own authentication patterns that differ from the main Camunda secret structure. These use the standard Bitnami PostgreSQL Helm chart pattern with existingSecret and secretKeys containing adminPasswordKey and userPasswordKey.

The following Bitnami subchart configurations are available:

  • identityPostgresql.auth - PostgreSQL database for Identity service
  • identityKeycloak.auth - Keycloak admin credentials
  • identityKeycloak.postgresql.auth - PostgreSQL database for Keycloak (when using Identity with Keycloak)
  • webModelerPostgresql.auth - PostgreSQL database for Web Modeler

Internal secrets

These secrets are used by Camunda applications and must be configured manually when using external secrets.

Secrets using the new pattern (Camunda 8.8+)

SecretChart values keyPurpose
Enterprise License Keyglobal.license.secretCamunda Enterprise license key
Identity First User Passwordidentity.firstUser.secretDefault user password (demo/demo)
OAuth Client Secret (Admin)global.identity.auth.admin.secretOAuth admin client secret for administrative operations
OAuth Client Secret (Console)global.identity.auth.console.secretOAuth client secret for Console
OAuth Client Secret (Connectors)connectors.security.authentication.oidc.secretOAuth client secret for connectors
OAuth Client Secret (Orchestration)orchestration.security.authentication.oidc.secretOAuth client secret for Orchestration Cluster
OAuth Client Secret (Optimize)global.identity.auth.optimize.secretOAuth client secret for Optimize

Secrets using Bitnami subchart patterns (all versions)

SecretChart values keyPurpose
Identity PostgreSQL PasswordidentityPostgresql.auth.existingSecretPassword for embedded PostgreSQL used by Identity
Keycloak Admin PasswordidentityKeycloak.auth.existingSecretAdmin password for Keycloak (Camunda Identity)
Keycloak PostgreSQL PasswordidentityKeycloak.postgresql.auth.existingSecretPassword for embedded PostgreSQL used by Keycloak
Web Modeler PostgreSQL PasswordwebModelerPostgresql.auth.existingSecretPasswords for Web Modeler's embedded PostgreSQL

PostgreSQL Secret Keys: For PostgreSQL subcharts, both adminPasswordKey and userPasswordKey are required:

  • adminPasswordKey: Password for the PostgreSQL administrator (typically used for administrative operations)
  • userPasswordKey: Password for the application-specific database user (used by the Camunda component)

External secrets

These secrets are necessary when integrating Camunda with third-party services.

Secrets using the new pattern (Camunda 8.8+)

SecretChart values keyPurpose
Identity External Database Passwordidentity.externalDatabase.secretPassword for external PostgreSQL if using an external DB for Identity
WebModeler External Database PasswordwebModeler.restapi.externalDatabase.secretPassword for external PostgreSQL if using an external DB for Web Modeler
SMTP PasswordwebModeler.restapi.mail.secretSMTP credentials for sending email notifications
External Elasticsearch Authglobal.elasticsearch.auth.secretPassword for external Elasticsearch authentication (basic auth)
External OpenSearch Authglobal.opensearch.auth.secretPassword for external OpenSearch authentication (basic auth)

How to configure secrets

Secrets can be configured in different ways depending on your Camunda version:

  • Camunda 8.8+: Use the new structured secret: pattern with inlineSecret for non-production or external Kubernetes Secrets for production
  • Camunda 8.7 and below: Use the legacy pattern with direct existingSecret fields

Method 1: Inline secrets (Camunda 8.8+, non-production only)

For development or testing environments, provide secrets directly in your values.yaml using the inlineSecret field:

global:
license:
secret:
inlineSecret: "my-license-key-here"

identity:
firstUser:
secret:
inlineSecret: "demo-password"

For production environments, create a Kubernetes Secret and reference it from your values.yaml. This method works for both Camunda 8.8+ (with new pattern) and 8.7 and below (with legacy pattern).

Step 1: Create the secret

Create a secret using kubectl or a YAML manifest:

kubectl create secret generic console-secret \
--from-literal=client-secret=camundapassword \
--namespace camunda

Or using YAML:

apiVersion: v1
kind: Secret
metadata:
name: console-secret
namespace: camunda
type: Opaque
stringData:
client-secret: "camundapassword"

Step 2: Reference in values.yaml

For components using the new pattern:

global:
identity:
auth:
console:
secret:
existingSecret: "console-secret"
existingSecretKey: "client-secret"

For Bitnami subchart components:

# PostgreSQL database for Identity service
identityPostgresql:
auth:
existingSecret: camunda-credentials
secretKeys:
adminPasswordKey: identity-postgresql-admin-password
userPasswordKey: identity-postgresql-user-password

# Keycloak admin credentials
identityKeycloak:
auth:
existingSecret: camunda-credentials
passwordSecretKey: identity-keycloak-admin-password

# PostgreSQL database for Keycloak (when using Identity with Keycloak)
identityKeycloak:
postgresql:
auth:
existingSecret: camunda-credentials
secretKeys:
adminPasswordKey: identity-keycloak-postgresql-admin-password
userPasswordKey: identity-keycloak-postgresql-user-password

# PostgreSQL database for Web Modeler
webModelerPostgresql:
auth:
existingSecret: camunda-credentials
secretKeys:
adminPasswordKey: web-modeler-postgresql-admin-password
userPasswordKey: web-modeler-postgresql-user-password

Auto-generated secrets

The Helm chart can automatically generate secrets with random passwords for both development and production environments. This removes the need to create secrets manually during initial setup. You can enable this feature during installation by setting --set global.secrets.autoGenerated=true.

Important limitations

The auto-generated secret uses Helm hooks (pre-install) with a keep resource policy. This means:

  • The secret is created before the main Helm release installation.
  • The secret is not managed by later Helm operations (upgrade, rollback, uninstall).
  • If you delete the secret, generated passwords are lost permanently.
  • The secret becomes orphaned from the Helm release lifecycle.

Configuring components to use auto-generated secrets

Enabling global.secrets.autoGenerated: true only creates the secret with random values. You must configure each component to reference the auto-generated secret by name and key. The key can be custom, but the name must match the definition above.

connectors:
security:
authentication:
oidc:
secret:
existingSecret: "camunda-credentials"
existingSecretKey: "identity-connectors-client-token"

For details on Identity secrets during installation, see the installation guide.

Document Store secrets

Document Store secrets now follow the structured secret: pattern introduced in Camunda 8.8+, with separate secret configurations for each credential component.

Secrets using the new pattern (Camunda 8.8+)

SecretChart values keyPurpose
AWS Document Store Access Key IDglobal.documentStore.type.aws.accessKeyId.secretAWS access key ID for S3 document storage authentication
AWS Document Store Secret Access Keyglobal.documentStore.type.aws.secretAccessKey.secretAWS secret access key for S3 document storage authentication
GCP Document Store Service Accountglobal.documentStore.type.gcp.secretGCP service account JSON for GCS document storage authentication

Secrets using the legacy pattern (deprecated)

The following legacy fields are deprecated in Camunda 8.8+ but remain functional during the transition period:

SecretChart values key (deprecated)Purpose
AWS Document Store Credentialsglobal.documentStore.type.aws.existingSecret, global.documentStore.type.aws.accessKeyIdKey, global.documentStore.type.aws.secretAccessKeyKeyAWS credentials for S3 document storage (requires multiple keys: access key ID and secret access key)
GCP Document Store Credentialsglobal.documentStore.type.gcp.existingSecret, global.documentStore.type.gcp.credentialsKey, global.documentStore.type.gcp.mountPath, global.documentStore.type.gcp.fileNameGCP service account JSON for GCS document storage (single key containing JSON file, with additional mount configuration for file-based access)

Migration from legacy pattern (8.7 → 8.8+)

If you are upgrading from Camunda 8.7 or earlier and using the legacy secret management pattern, migrate to the new structured secret: pattern available in Camunda 8.8+ for better consistency and future compatibility. The legacy fields are deprecated in 8.8+ but will remain functional during the transition period.

warning

The new pattern requires you to configure both existingSecret and existingSecretKey. Unlike the legacy pattern, which provided default key values, the new pattern has no defaults. You must specify the exact secret name and key for each component.

This explicit configuration improves security and removes ambiguity but requires more setup.

Scenario 1: Migrating an external secret reference

This scenario applies when your legacy configuration references a Kubernetes secret by name.

Legacy configuration:

global:
identity:
auth:
console:
existingSecret:
name: console-secret
existingSecretKey: client-secret

New configuration:

global:
identity:
auth:
console:
secret:
existingSecret: console-secret
existingSecretKey: client-secret

Scenario 2: Migrating a plaintext secret

This scenario applies when your legacy configuration provided a plaintext string directly in existingSecret.

Legacy configuration:

global:
identity:
auth:
console:
existingSecret: "my-plaintext-secret"

New configuration:

global:
identity:
auth:
console:
secret:
inlineSecret: "my-plaintext-secret"

Scenario 3: Migrating AWS Document Store secrets

This scenario applies when migrating from the legacy single-secret AWS document store configuration to the new separate secrets pattern.

Legacy configuration:

global:
documentStore:
type:
aws:
existingSecret: "aws-credentials"
accessKeyIdKey: "awsAccessKeyId"
secretAccessKeyKey: "awsSecretAccessKey"

New configuration (using separate secrets):

global:
documentStore:
type:
aws:
accessKeyId:
secret:
existingSecret: "aws-access-key-secret"
existingSecretKey: "access-key-id"
secretAccessKey:
secret:
existingSecret: "aws-secret-key-secret"
existingSecretKey: "secret-access-key"

TLS certificates

For TLS-enabled services, you'll need to configure certificate secrets.

Secrets using the legacy pattern (all versions)

SecretChart values keyPurpose
Console TLS Certificateconsole.tls.existingSecretTLS certificate for Console web application
External Elasticsearch TLS Certglobal.elasticsearch.tls.existingSecretTLS certificate for external Elasticsearch over SSL
External OpenSearch TLS Certglobal.opensearch.tls.existingSecretTLS certificate for external OpenSearch over SSL

Ingress TLS

Configure TLS for Camunda services exposed via Ingress:

global:
ingress:
tls:
enabled: true
secretName: camunda-platform

External service TLS

For external Elasticsearch or OpenSearch with TLS, configure the TLS certificate using the legacy pattern:

global:
elasticsearch:
tls:
enabled: true
existingSecret: elasticsearch-tls-secret

Console TLS (legacy pattern)

console:
tls:
enabled: true
existingSecret: console-tls-secret
certKeyFilename: tls.key

Create TLS secrets using the standard Kubernetes TLS secret type:

apiVersion: v1
kind: Secret
metadata:
name: camunda-platform
namespace: camunda
type: kubernetes.io/tls
data:
tls.crt: <base64 encoded cert>
tls.key: <base64 encoded key>