Skip to main content
Version: 8.9 (unreleased)

Install Camunda 8 on an EKS cluster

This guide provides a comprehensive walkthrough for installing the Camunda 8 Helm chart on your existing AWS Kubernetes EKS cluster. It also includes instructions for setting up optional DNS configurations and other optional AWS-managed services, such as OpenSearch and PostgreSQL.

Lastly you'll verify that the connection to your Self-Managed Camunda 8 environment is working.

Requirements​

  • A Kubernetes cluster; see the eksctl or Terraform guide.
  • Helm
  • kubectl to interact with the cluster.
  • jq to interact with some variables.
  • GNU envsubst to generate manifests.
  • (optional) Domain name/hosted zone in Route53. This allows you to expose Camunda 8 and connect via community-supported zbctl or Camunda Modeler.
  • A namespace to host the Camunda Platform.

For the tool versions used, check the .tool-versions file in the repository. It contains an up-to-date list of versions that we also use for testing.

Considerations​

While this guide is primarily tailored for UNIX systems, it can also be run under Windows by utilizing the Windows Subsystem for Linux.

Multi-tenancy is disabled by default and is not covered further in this guide. If you decide to enable it, you may use the same PostgreSQL instance and add an extra database for multi-tenancy purposes.

Optimize compatibility with OpenSearch

Migration: The migration step will be disabled during the installation. For more information, refer to using Amazon OpenSearch Service.

Architecture​

In addition to the infrastructure diagram provided in the Terraform setup guide, this section installs Camunda 8 following the architecture described in the reference architecture.

The architecture includes the following core components:

  • Orchestration Cluster: Core process execution engine (Zeebe, Operate, Tasklist, and Identity)
  • Web Modeler and Console: Management and design tools (Web Modeler, Console, and Management Identity)

To demonstrate how to deploy with a custom domain, the following stack is also included:

  • cert-manager: Automates TLS certificate management with Let's Encrypt
  • external-dns: Manages DNS record in Route53 for domain ownership confirmation
  • ingress-nginx: Provides HTTP/HTTPS load balancing and routing to Kubernetes services
Single namespace deployment

This guide uses a single Kubernetes namespace for simplicity, since the deployment is done with a single Helm chart. This differs from the reference architecture, which recommends separating Orchestration Cluster and Web Modeler or Console into different namespaces in production to improve isolation and enable independent scaling.

Export environment variables​

To streamline the execution of the subsequent commands, it is recommended to export multiple environment variables.

Export the AWS region and Helm chart version​

The following are the required environment variables with some example values:

aws/kubernetes/eks-single-region/procedure/setting-region.sh
loading...
generic/kubernetes/single-region/procedure/chart-env.sh
loading...
  • CAMUNDA_NAMESPACE is the Kubernetes namespace where Camunda will be installed.
  • CAMUNDA_RELEASE_NAME is the name of the Helm release associated with this Camunda installation.

Export database values​

When using either standard authentication (network based or username and password) or IRSA authentication, specific environment variables must be set with valid values. Follow the guide for either eksctl or Terraform to set them correctly.

Verify the configuration of your environment variables by running the following loop:

aws/kubernetes/eks-single-region/procedure/check-env-variables.sh
loading...

(Optional) Ingress Setup​

Domain or domainless installation

If you do not have a domain name, external access to Camunda 8 web endpoints from outside the AWS VPC will not be possible. In this case, you may skip the DNS setup and proceed directly to deploying Camunda 8 via Helm charts.

Alternatively, you can use kubectl port-forward to access the Camunda platform without a domain or Ingress configuration. For more information, see the kubectl port-forward documentation.

Throughout the rest of this installation guide, we will refer to configurations as "With domain" or "Without domain" depending on whether the application is exposed via a domain.

In this section, we provide an optional setup guide for configuring an Ingress with TLS and DNS management, allowing you to access your application through a specified domain. If you haven't set up an Ingress, refer to the Kubernetes Ingress documentation for more details. In Kubernetes, an Ingress is an API object that manages external access to services in a cluster, typically over HTTP, and can also handle TLS encryption for secure connections.

To monitor your Ingress setup using Amazon CloudWatch, you may also find the official AWS guide on monitoring nginx workloads with CloudWatch Container Insights and Prometheus helpful. Additionally, for detailed steps on exposing Kubernetes applications with the nginx ingress controller, refer to the official AWS tutorial.

Export Values​

Set the following values for your Ingress configuration:

generic/kubernetes/single-region/procedure/export-ingress-setup-vars.sh
loading...

Additionally, obtain these values by following the guide for either eksctl or Terraform, as they will be needed in later steps:

  • EXTERNAL_DNS_IRSA_ARN
  • CERT_MANAGER_IRSA_ARN
  • REGION

ingress-nginx​

Ingress-nginx is an open-source Kubernetes Ingress controller that provides a way to manage external access to services within a Kubernetes cluster. It acts as a reverse proxy and load balancer, routing incoming traffic to the appropriate services based on rules defined in the Ingress resource.

The following installs ingress-nginx in the ingress-nginx namespace via Helm. For more configuration options, consult the Helm chart.

aws/kubernetes/eks-single-region/procedure/install-ingress-nginx.sh
loading...

external-dns​

External-dns is a Kubernetes add-on that automates the management of DNS records for external resources, such as load balancers or Ingress controllers. It monitors the Kubernetes resources and dynamically updates the DNS provider with the appropriate DNS records.

The following installs external-dns in the external-dns namespace via Helm. For more configuration options, consult the Helm chart.

Consider setting domainFilters via --set to restrict access to certain hosted zones.

tip

Make sure to have EXTERNAL_DNS_IRSA_ARN exported prior by either having followed the eksctl or Terraform guide.

Uniqueness of txtOwnerId for DNS

If you are already running external-dns in a different cluster, ensure each instance has a unique txtOwnerId for the TXT record. Without unique identifiers, the external-dns instances will conflict and inadvertently delete existing DNS records.

In the example below, it's set to external-dns and should be changed if this identifier is already in use. Consult the documentation to learn more about DNS record ownership.

aws/kubernetes/eks-single-region/procedure/install-external-dns.sh
loading...

cert-manager​

Cert-manager is an open-source Kubernetes add-on that automates the management and issuance of TLS certificates. It integrates with various certificate authorities (CAs) and provides a straightforward way to obtain, renew, and manage SSL/TLS certificates for your Kubernetes applications.

To simplify the installation process, it is recommended to install the cert-manager CustomResourceDefinition resources before installing the chart. This separate step allows for easy uninstallation and reinstallation of cert-manager without deleting any custom resources that have been installed.

generic/kubernetes/single-region/procedure/install-cert-manager-crds.sh
loading...

The following installs cert-manager in the cert-manager namespace via Helm. For more configuration options, consult the Helm chart. The supplied settings also configure cert-manager to ease the certificate creation by setting a default issuer, which allows you to add a single annotation on an Ingress to request the relevant certificates.

tip

Make sure to have CERT_MANAGER_IRSA_ARN exported prior by either having followed the eksctl or Terraform guide.

aws/kubernetes/eks-single-region/procedure/install-cert-manager.sh
loading...

Create a ClusterIssuer via kubectl to enable cert-manager to request certificates from Let's Encrypt:

aws/kubernetes/eks-single-region/procedure/install-cert-manager-issuer.sh
loading...

Identity Provider (IdP) setup​

An OIDC-compatible identity provider (IdP) is required. This reference architecture does not include an IdP. You must configure your own before proceeding. Options include:

After deploying your IdP, merge the corresponding auth overlay into your values.yml using yq before running envsubst:

Keycloak Operator overlays:

# Merge the Keycloak Operator Helm values (use "domain" or "no-domain" variant)
yq ". *+ load(\"camunda-keycloak-domain-values.yml\")" values.yml > values-merged.yml && mv values-merged.yml values.yml

# Merge the identity secrets overlay
yq ". *+ load(\"camunda-values-identity-secrets.yml\")" values.yml > values-merged.yml && mv values-merged.yml values.yml

The overlay files are available in the Keycloak operator-based directory. The identity secrets are created automatically by the Keycloak Operator.

No-domain deployments and IdP choice

If you deploy Camunda without a domain (using kubectl port-forward), you'll generally need to use Keycloak as your IdP. Most external OIDC providers (for example, Microsoft Entra ID and Okta) don't allow localhost as a valid redirect URI for security reasons. Keycloak, when deployed locally in the cluster, can be configured to accept localhost-based redirect URIs.

Why isn't an IdP included by default?

The choice of identity provider is highly specific to each organization's security requirements, existing infrastructure, and compliance needs. Rather than bundling a default IdP that may not match your setup, the reference architecture leaves this choice to you.

Deploy Camunda 8 via Helm charts​

For more configuration options, refer to the Helm chart documentation. Additionally, explore our existing resources on the Camunda 8 Helm chart and guides.

Depending of your installation path, you may use different settings. For easy and reproducible installations, we will use yaml files to configure the chart.

1. Create the values.yml file​

Start by creating a values.yml file to store the configuration for your environment. This file will contain key-value pairs that will be substituted using envsubst. You can find a reference example of this file here:

Database initialization prerequisite

If you're using an external Aurora PostgreSQL database, you must create the individual component databases (Identity and Web Modeler) before installing the Helm chart. This initialization step is covered in the infrastructure setup guides:

Without this step, the Camunda components will fail to connect to their databases.

The following makes use of the combined Ingress setup by deploying a single Ingress for all HTTP components and a separate Ingress for the gRPC endpoint.

Cert-manager annotation for domain installation

The annotation kubernetes.io/tls-acme=true will be interpreted by cert-manager and automatically results in the creation of the required certificate request, easing the setup.

aws/kubernetes/eks-single-region/helm-values/values-domain.yml
loading...
Exposure of the Zeebe Gateway Service

For production-grade security, keep the Zeebe Gateway on a private network (no public Ingress) and access it only from internal workloads or through a secure VPN connection. This limits the attack surface and ensures workflow and job traffic remain inside your trusted network boundary. See the VPN module setup for guidance on establishing secure remote access to a private EKS cluster.

Additionally, implement fine-grained Kubernetes NetworkPolicies to explicitly allow only required internal components to initiate connections to the Zeebe Gateway Service. Deny all other Ingress traffic at the network layer to reduce blast radius if another workload in the cluster is compromised.

Reference the credentials in secrets​

Before installing the Helm chart, create Kubernetes secrets to store the database authentication credentials.

To create the secrets, run the following commands:

aws/kubernetes/eks-single-region/procedure/create-external-db-secrets.sh
loading...

2. Configure your deployment​

Enable Enterprise components​

Some components are not enabled by default in this deployment. For more information on how to configure and enable these components, refer to configuring Web Modeler, Console, and connectors.

Use internal Elasticsearch instead of the managed OpenSearch​

If you do not wish to use a managed OpenSearch service, you can opt to use the internal Elasticsearch deployment. This configuration disables OpenSearch and enables the internal Kubernetes Elasticsearch deployment:

Alternative: Operator-based Elasticsearch deployment

Instead of using Bitnami subcharts for internal Elasticsearch, consider deploying Elastic Cloud on Kubernetes (ECK) for a production-grade setup with automated scaling, upgrades, and built-in security.

Show configuration changes to disable external OpenSearch usage
global:
  elasticsearch:
    enabled: true
  opensearch:
    enabled: false

elasticsearch:
  enabled: true

Use internal PostgreSQL instead of the managed Aurora​

If you prefer not to use an external PostgreSQL service, you can switch to the internal PostgreSQL deployment. In this case, you will need to configure the Helm chart as follows and remove certain configurations related to the external database and service account:

Alternative: Operator-based PostgreSQL deployment

Instead of using Bitnami subcharts for internal PostgreSQL, consider using CloudNativePG operator for production-grade PostgreSQL clusters with automated backup, monitoring, and scaling capabilities.

Show configuration changes to disable external database usage
webModelerPostgresql:
  enabled: true

webModeler:
  # Remove this part

  # restapi:
  #     externalDatabase:
  #         url: jdbc:aws-wrapper:postgresql://${DB_HOST}:5432/${DB_WEBMODELER_NAME}
  #         user: ${DB_WEBMODELER_USERNAME}
  #         ...

identity:
  # Remove this part

  # externalDatabase:
  #     enabled: true
  #     host: ${DB_HOST}
  #     port: 5432
  #     username: ${DB_IDENTITY_USERNAME}
  #     database: ${DB_IDENTITY_NAME}
  #     ...

Fill your deployment with actual values​

Once you've prepared the values.yml file, run the following envsubst command to substitute the environment variables with their actual values:

generic/kubernetes/single-region/procedure/assemble-envsubst-values.sh
loading...
Web Modeler SMTP secret

If you plan to enable Web Modeler, create the SMTP secret required for email notifications (see how it's used by Web Modeler):

aws/kubernetes/eks-single-region/procedure/create-webmodeler-secret.sh
loading...

3. Install Camunda 8 using Helm​

Now that the generated-values.yml is ready, you can install Camunda 8 using Helm. Run the following command:

generic/kubernetes/single-region/procedure/install-chart.sh
loading...

This command:

  • Installs (or upgrades) the Camunda platform using the Helm chart.
  • Substitutes the appropriate version using the $CAMUNDA_HELM_CHART_VERSION environment variable.
  • Applies the configuration from generated-values.yml.
note

This guide uses helm upgrade --install as it runs install on initial deployment and upgrades future usage. This simplifies future Camunda 8 Helm upgrades or any other component upgrades.

You can track the progress of the installation using the following command:

generic/kubernetes/single-region/procedure/check-deployment-ready.sh
loading...
Understand how each component interacts with IRSA

Web Modeler​

As the Web Modeler REST API uses PostgreSQL, configure the restapi to use IRSA with Amazon Aurora PostgreSQL. Check the Web Modeler database configuration for more details. Web Modeler already comes fitted with the aws-advanced-jdbc-wrapper within the Docker image.

Identity​

Identity uses PostgreSQL, and identity is configured to use IRSA with Amazon Aurora PostgreSQL. Check the Identity database configuration for more details. Identity includes aws-advanced-jdbc-wrapper within the Docker image.

Keycloak with IRSA

If you deploy Keycloak via the Keycloak Operator and want it to use IRSA for database access, refer to the official Keycloak documentation for instructions on configuring Amazon Aurora PostgreSQL with a custom JDBC wrapper.

Amazon OpenSearch Service​

Internal database configuration​

The default setup is sufficient for Amazon OpenSearch Service clusters without fine-grained access control.

Fine-grained access control adds another layer of security to OpenSearch, requiring you to add a mapping between the IAM role and the internal OpenSearch role. Visit the AWS documentation on fine-grained access control.

There are different ways to configure the mapping within Amazon OpenSearch Service:

  • Via a Terraform module in case your OpenSearch instance is exposed.

  • Via the OpenSearch dashboard.

  • Via the REST API. To authorize the IAM role in OpenSearch for access, follow these steps:

    Use the following curl command to update the OpenSearch internal database and authorize the IAM role for access. Replace placeholders with your specific values:

    aws/kubernetes/eks-single-region-irsa/setup-opensearch-fgac.yml
    loading...
    • Replace OPENSEARCH_MASTER_USERNAME and OPENSEARCH_MASTER_PASSWORD with your OpenSearch domain admin credentials.
    • Replace OPENSEARCH_HOST with your OpenSearch endpoint URL.
    • Replace OPENSEARCH_ROLE_ARN with the IAM role name created by Terraform, which is output by the opensearch_role module.
    Security of basic auth usage

    This example uses basic authentication (username and password), which may not be the best practice for all scenarios, especially if fine-grained access control is enabled. The endpoint used in this example is not exposed by default, so consult your OpenSearch documentation for specifics on enabling and securing this endpoint.

Ensure that the iam_role_arn of the previously created opensearch_role is assigned to an internal role within Amazon OpenSearch Service. For example, all_access on the Amazon OpenSearch Service side is a good candidate, or if required, extra roles can be created with more restrictive access.

Verify connectivity to Camunda 8​

First, we need an OAuth client to be able to connect to the Camunda 8 cluster.

Generate an M2M token using Identity​

Generate an M2M token by following the steps outlined in the Identity getting started guide, along with the incorporating applications documentation.

Below is a summary of the necessary instructions:

  1. Open Identity in your browser at https://${CAMUNDA_DOMAIN}/managementidentity. You will be redirected to your IdP and prompted to log in.
  2. Log in with the initial user admin (defined in identity.firstUser of the values file). Retrieve the generated password (created earlier when running the secret creation script) from the Kubernetes secret and use it to authenticate:
kubectl get secret identity-secret-for-components \
  --namespace "$CAMUNDA_NAMESPACE" \
  -o jsonpath='{.data.identity-first-user-password}' | base64 -d; echo
  1. Select Add application and select M2M as the type. Assign a name like "test."
  2. Select the newly created application. Then, select Access to APIs > Assign permissions, and select the Orchestration API with "read" and "write" permission.
  3. Retrieve the client-id and client-secret values from the application details
export ZEEBE_CLIENT_ID='client-id' # retrieve the value from the identity page of your created m2m application
export ZEEBE_CLIENT_SECRET='client-secret' # retrieve the value from the identity page of your created m2m application
  1. Open the Orchestration Cluster Identity in your browser at https://${CAMUNDA_DOMAIN}/identity and log in with the user admin (defined in identity.firstUser of the values file).
  2. In the Identity navigation menu, select Roles.
  3. Either select an existing role (for example, Admin) or create a new role with the appropriate permissions for your use case.
  4. In the selected role view, open the Clients tab and click Assign client.
  5. Enter the client ID of your application created in Management Identity (for example, test) and click Assign client to save.

This operation links the OIDC client to the role's permissions in the Orchestration Cluster, granting the application access to the cluster resources. For more information about managing roles and clients, see Roles.

Use the token​

For a detailed guide on generating and using a token, consult the relevant documentation on authenticating with the Orchestration Cluster REST API.

Export the following environment variables:

generic/kubernetes/single-region/procedure/export-verify-zeebe-domain.sh
loading...

Generate a temporary token to access the Orchestration Cluster REST API, then capture the value of the access_token property and store it as your token. Use the stored token (referred to as TOKEN in this case) to interact with the Orchestration Cluster REST API and display the cluster topology:

generic/kubernetes/single-region/procedure/check-zeebe-cluster-topology.sh
loading...

...and results in the following output:

Example output
generic/kubernetes/single-region/procedure/check-zeebe-cluster-topology-output.json
loading...

Advanced topics​

The following are some advanced configuration topics to consider for your cluster:

To get more familiar with our product stack, visit the following topics: