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.

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.

Install the orchestration cluster​

  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

Install a specific version (optional)​

The Camunda 8 Helm chart automatically selects the latest version of the Camunda 8 applications. Because the Helm chart and application components are released independently, minor version differences may occur.

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

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

To install a previous version, run:

helm install camunda camunda/camunda-platform --version 8.7 \
    --values https://helm.camunda.io/camunda-platform/values/values-v8.7.yaml

Access the orchestration cluster​

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

kubectl port-forward svc/camunda-core 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, basic authentication is configured in the orchestration cluster. Use the default credentials:

username: demo
password: demo

Access Camunda services​

By default, Camunda services deployed in a Kubernetes cluster are not accessible from outside the cluster. You can expose these services externally in the following ways:

  • Port forwarding: Direct traffic from your local machine to the cluster to access Camunda services. See Access components without Ingress.
  • Ingress configuration: Use the NGINX Ingress controller to manage external service access. See Ingress setup.
  • Amazon EKS installation: If you are deploying Camunda 8 on an Amazon EKS cluster, see Install Camunda 8 on EKS.

Enable other components​

note

This step is optional.

The following components run outside the orchestration cluster:

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

These components are disabled by default. They do not support basic authentication, so you must use another method such as Keycloak or OIDC. In this example, we use Keycloak.

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.
  • Enable other Camunda components that run outside the orchestration cluster.

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

global:
  identity:
    auth:
      enabled: true
      #needs to be added in base values.yaml
      publicIssuerUrl: "http://camunda-keycloak/auth/realms/camunda-platform"
      admin:
        enabled: true
        existingSecret:
          name: "integration-test-credentials"
      webModeler:
        redirectUrl: "http://camunda-modeler"
      console:
        redirectUrl: "http://camunda-console"
        existingSecret:
          name: "integration-test-credentials"
      optimize:
        redirectUrl: "http://camunda-optimize"
        existingSecret:
          name: "integration-test-credentials"
      #######################
      # Orchestration Group
      #######################
      orchestration:
        redirectUrl: "http://camunda-core:8080"
        existingSecret:
          name: "integration-test-credentials"
      connectors:
        existingSecret:
          name: "integration-test-credentials"
  security:
    authentication:
      method: oidc

identity:
  enabled: true
  firstUser:
    existingSecret: "integration-test-credentials"

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

optimize:
  enabled: true

connectors:
  inbound:
    mode: oauth

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: "integration-test-credentials"
    secretKeys:
      adminPasswordKey: "webmodeler-postgresql-admin-password"
      userPasswordKey: "webmodeler-postgresql-user-password"

orchestration:
  enabled: true
  clusterSize: "1"
  partitionCount: "1"
  replicationFactor: "1"
  env:
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_0_MAPPINGID
      value: "demo-user-mapping"
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_0_CLAIMNAME
      value: "preferred_username"
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_0_CLAIMVALUE
      value: "demo"
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_1_MAPPINGID
      value: "connectors-client-mapping"
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_1_CLAIMNAME
      value: "client_id"
    - name: CAMUNDA_SECURITY_INITIALIZATION_MAPPINGS_1_CLAIMVALUE
      value: "connectors"
    - name: CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_ADMIN_MAPPINGS_0
      value: "demo-user-mapping"
    - name: CAMUNDA_SECURITY_INITIALIZATION_DEFAULTROLES_ADMIN_MAPPINGS_1
      value: "connectors-client-mapping"

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.

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 gateway is deployed as a stateless service. It supports Kubernetes startup and liveness probes. See Gateway health probes.
  • Zeebe broker nodes 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 open-source images from Bitnami. For enterprise installations, Camunda recommends using enterprise images. For instructions, see Registry and images.

Additional resources​