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:

New pattern (Camunda 8.8+, recommended)

Starting with Camunda 8.8, the new pattern uses a structured secret: configuration under components. This block supports 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 fields are deprecated in 8.8+ but remain supported for backward compatibility.

Bitnami subchart pattern

Some components use Bitnami subcharts for database services such as PostgreSQL. These subcharts follow their own authentication patterns, which differ from the main Camunda secret structure. They use the standard Bitnami PostgreSQL Helm chart pattern, which uses 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

Camunda applications use the following secrets. You must configure them manually when using external secrets.

Secrets using the new pattern (Camunda 8.8+)

Secret	Chart values key	Purpose
Enterprise License Key	global.license.secret	Camunda Enterprise license key
Identity First User Password	identity.firstUser.secret	Default user password (demo/demo)
OAuth Client Secret (Admin)	global.identity.auth.admin.secret	OAuth admin client secret for administrative operations
OAuth Client Secret (Console)	global.identity.auth.console.secret	OAuth client secret for Console
OAuth Client Secret (Connectors)	global.identity.auth.connectors.secret	OAuth client secret for connectors
OAuth Client Secret (Orchestration)	global.identity.auth.orchestration.secret	OAuth client secret for Orchestration cluster
OAuth Client Secret (Optimize)	global.identity.auth.optimize.secret	OAuth client secret for Optimize

Secrets using Bitnami subchart patterns (all versions)

Secret	Chart values key	Purpose
Identity PostgreSQL Password	identityPostgresql.auth.existingSecret	Password for embedded PostgreSQL used by Identity
Keycloak Admin Password	identityKeycloak.auth.existingSecret	Admin password for Keycloak (Camunda Identity)
Keycloak PostgreSQL Password	identityKeycloak.postgresql.auth.existingSecret	Password for embedded PostgreSQL used by Keycloak
Web Modeler PostgreSQL Password	webModelerPostgresql.auth.existingSecret	Passwords for Web Modeler's embedded PostgreSQL

PostgreSQL secret keys

For PostgreSQL subcharts, the following keys 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 required when integrating Camunda with third-party services.

Secrets using the new pattern (Camunda 8.8+)

Secret	Chart values key	Purpose
Identity External Database Password	identity.externalDatabase.secret	Password for external PostgreSQL if using an external DB for Identity
WebModeler External Database Password	webModeler.restapi.externalDatabase.secret	Password for external PostgreSQL if using an external DB for Web Modeler
SMTP Password	webModeler.restapi.mail.secret	SMTP credentials for sending email notifications
External Elasticsearch Auth	global.elasticsearch.auth.secret	Password for external Elasticsearch authentication (basic auth)
External Elasticsearch TLS Cert	global.elasticsearch.tls.secret	TLS certificate for external Elasticsearch over SSL
External OpenSearch Auth	global.opensearch.auth.secret	Password for external OpenSearch authentication (basic auth)
External OpenSearch TLS Cert	global.opensearch.tls.secret	TLS certificate for external OpenSearch over SSL

How to configure secrets

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

• Camunda 8.8+: Use the 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"

Method 2: External Kubernetes secrets (recommended for all versions)

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

Step 1: Create the secret

Create a secret using kubectl or a YAML manifest:

• kubectl:

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

• 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

For additional details on Identity secrets during installation, see Helm chart installation.

Document store secrets

Document store secrets are configured using direct existingSecret references, with multiple key specifications for different credential components.

Secret	Chart values key	Purpose
AWS Document Store Credentials	global.documentStore.type.aws.existingSecret, global.documentStore.type.aws.accessKeyIdKey, global.documentStore.type.aws.secretAccessKeyKey	AWS credentials for S3 document storage (requires multiple keys: access key ID and secret access key)
GCP Document Store Credentials	global.documentStore.type.gcp.existingSecret, global.documentStore.type.gcp.credentialsKey, global.documentStore.type.gcp.mountPath, global.documentStore.type.gcp.fileName	GCP 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 structured secret: pattern available in Camunda 8.8+. This ensures consistency and prepares for future compatibility. The legacy fields are deprecated in 8.8+ but remain functional during the transition period.

Migrate an external secret reference

This applies if 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

Migrate a plaintext secret

This applies if 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"

TLS certificates

Configure certificate secrets for TLS-enabled services.

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, use the new secret pattern:

global:
  elasticsearch:
    tls:
      enabled: true
      secret:
        existingSecret: elasticsearch-tls-secret
        existingSecretKey: tls.crt

Console TLS (legacy pattern)

• Configure TLS for Console with the 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>