Skip to main content
Version: 8.8 (unreleased)

Install Camunda with Helm

Use this guide to install Camunda 8 Self-Managed with the orchestration cluster, and optionally enable additional components.

note

By default, the Camunda Helm chart uses Bitnami open-source images. For production environments, Camunda recommends switching to vendor-supported enterprise images. This guide explains how to create registry secrets and install Camunda with enterprise images.

Prerequisites​

  • Kubernetes cluster: A functioning Kubernetes cluster with kubectl access and block-storage persistent volumes for stateful components. See Cloud providers for instructions to create a Kubernetes cluster.
  • Helm: The Helm CLI installed. See Installing Helm.

Overview​

There are two main ways to install Camunda Helm Charts, depending on your requirements.

Orchestration Cluster only

Deploys only a small set of necessary components (Orchestration Cluster and connectors). Quicker and good enough for most development and testing.

Full Cluster

Deploys Orchestration Cluster, Connectors, Management Identity, Console, and Optimize.

Orchestration Cluster only​

  1. Create a namespace to install the platform on Kubernetes: 
    kubectl create namespace orchestration
    output: 
    namespace/orchestration created
  2. To install the Camunda 8 Self-Managed Helm chart, add the Helm repository with the following command: 
    helm repo add camunda https://helm.camunda.io
    helm repo update
  3. Install the Helm chart on your namespace: 
    helm install camunda camunda/camunda-platform -n orchestration
  4. Access the components

Install a specific version (optional)​

By default, the Camunda Helm chart installs the latest version of the Camunda 8 applications. Because Helm chart and application versions are released independently, their version numbers differ. For details, see the Camunda 8 Helm Chart Version Matrix.

To install the latest version of the chart and its application dependencies, run:

helm install camunda camunda/camunda-platform --version $HELM_CHART_VERSION \
    --values https://helm.camunda.io/camunda-platform/values/values-latest.yaml

To install a specific chart version, use the --version flag with the chart version number. For example, the chart version for Camunda 8.8 is 13:

helm install camunda camunda/camunda-platform --version 13 \
    --values https://helm.camunda.io/camunda-platform/values/values-v8.8.yaml

Specifying only the major chart version (for example, 13) installs the latest available 13.x.y release. You can also specify a minor version (for example, 12.6) to install the latest 12.6.y release.

If you are unsure which chart version corresponds to your Camunda application version, run:

helm search repo -l camunda/camunda-platform

This command lists all available chart versions and their corresponding application versions.

Full Cluster​

The following components run outside the orchestration cluster and are disable by default in Helm Charts:

  • Optimize
  • Web Modeler
  • Console
  • Management Identity
  • Keycloak

These components do not support basic authentication, so you must use any OIDC provider. In the following example, we use Keycloak as a locally running OIDC provider. The values file will deploy all Camunda 8 components.

Because the default configuration of the Helm chart uses basic authentication, you need to create a values.yaml file to modify the default configuration to:

  • Enable Keycloak to provide another method of authentication via OIDC.
  • Enable other Camunda components that run alongside the orchestration cluster.

Create a file called camunda-values.yaml with the following content:

global:
  secrets:
    autoGenerated: true
    name: "camunda-credentials"
  identity:
    auth:
      enabled: true
      publicIssuerUrl: "http://localhost:18080/auth/realms/camunda-platform"
      webModeler:
        redirectUrl: "http://localhost:8070"
      console:
        redirectUrl: "http://localhost:8087"
        existingSecret:
          name: "camunda-credentials"
      optimize:
        redirectUrl: "http://localhost:8083"
        existingSecret:
          name: "camunda-credentials"
      #######################
      # Orchestration Group
      #######################
      orchestration:
        redirectUrl: "http://localhost:8080"
        existingSecret:
          name: "camunda-credentials"
      connectors:
        existingSecret:
          name: "camunda-credentials"
  security:
    authentication:
      method: oidc

identity:
  enabled: true
  firstUser:
    existingSecret: "camunda-credentials"

identityKeycloak:
  enabled: true
  postgresql:
    auth:
      existingSecret: "camunda-credentials"
      secretKeys:
        adminPasswordKey: "identity-keycloak-postgresql-admin-password"
        userPasswordKey: "identity-keycloak-postgresql-user-password"
  auth:
    existingSecret: "camunda-credentials"
    passwordSecretKey: "identity-keycloak-admin-password"

optimize:
  enabled: true

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

webModeler:
  enabled: true
  restapi:
    mail:
      # This value is required, otherwise the restapi pod wouldn't start.
      fromAddress: noreply@example.com

# WebModeler Database.
webModelerPostgresql:
  enabled: true
  auth:
    existingSecret: "camunda-credentials"
    secretKeys:
      adminPasswordKey: "webmodeler-postgresql-admin-password"
      userPasswordKey: "webmodeler-postgresql-user-password"

orchestration:
  enabled: true
  clusterSize: "1"
  partitionCount: "1"
  replicationFactor: "1"
  security:
    authentication:
      method: oidc
      oidc:
        redirectUrl: "http://localhost:8080"
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-orchestration-client-token"

console:
  enabled: true

Installing all components in a cluster requires downloading all related Docker images to the Kubernetes nodes. The time required depends on your cloud provider and network speed.

For more information about enabling other components, see Enable Web Modeler, Console, and Connectors.

Access the components​

Run the following command to locally port-forward the orchestration cluster pod to access the UI:

kubectl port-forward svc/camunda-zeebe-gateway 8080:8080

Use the following URLs to access the orchestration cluster UIs:

http://localhost:8080/identity
http://localhost:8080/operate
http://localhost:8080/tasklist

By default, the Helm chart deploys the Camunda orchestration cluster with basic authentication, intended only for testing and development. In production, Camunda 8 is typically deployed together with additional applications such as Optimize, Web Modeler, and Console, which require OIDC-based authentication (for example, using Keycloak). For details, see the Full Cluster section.

For basic authentication use the default credentials:

username: demo
password: demo

Troubleshoot installation issues​

Verify that each pod is running and ready. If a pod is pending, it cannot be scheduled onto a node. This usually happens when the cluster does not have enough resources. To check messages from the scheduler, run:

kubectl describe pods <POD_NAME>

If the describe output does not help, check the pod logs by running:

kubectl logs -f <POD_NAME>

Notes and requirements​

  • Zeebe supports Kubernetes startup and liveness probes. See Gateway health probes.
  • Zeebe must be deployed as a StatefulSet to preserve cluster node identities. StatefulSets require persistent storage, which you must provision in advance. The type of storage depends on your cloud provider.
  • Docker pull limits apply when downloading Camunda 8 images from Docker Hub. To avoid disruptions, authenticate with Docker Hub or use a mirror registry.
  • Air-gapped environments require additional configuration. See Helm chart air-gapped environment installation.
  • Image sources: By default, the Helm chart uses Bitnami open-source images for infrastructure dependencies (PostgreSQL, Elasticsearch, Keycloak). For production environments, Camunda recommends using Bitnami Premium images for enhanced security and vendor support. For detailed information about image types, CVE handling policies, and installation procedures, see Install Bitnami enterprise images.

Next steps​

Additional resources​