Get started with microservice orchestration

BeginnerTime estimate: 25 minutes

Using Camunda 8, you can orchestrate the microservices necessary to achieve your end-to-end automated business process. Whether you have existing microservices or are looking to build out your microservices, this guide will help you understand how you can start your microservice orchestration journey with Camunda 8.

While this guide uses code snippets in Java, you do not need to be a Java developer to be successful. Additionally, you can orchestrate microservices with Camunda 8 in other programming languages.

Prerequisites

You must have access to either a local or remote Camunda Self-Managed installation or a SaaS account.

Self-Managed

Have you installed Camunda yet?

Prerequisites

Before getting started, ensure you:

• Can access your preferred code editor or IDE.
• Install Desktop Modeler.

Starting in 8.6.0-alpha2, you can install Camunda 8 Self-Managed as an integrated plain Java application.

For this installation, you must have:

• OpenJDK 21+ locally installed
• Camunda 8.6.0-alpha2 or later

Download and configure Elasticsearch

danger

Disabling Elasticsearch's security packages is for non-production only!

1. Download Elasticsearch 8.9.2 and follow the installation instructions.
2. Navigate to the directory where you installed Elasticsearch, and open /config/elasticsearch.yml. Add the line xpack.security.enabled: false to the bottom of the configuration to disable Elasticsearch's security packages.
3. Start Elasticsearch by running ELASTICSEARCH_HOME/bin/elasticsearch (or ELASTICSEARCH_HOME\bin\elasticsearch.bat on Windows).

Confirm Elasticsearch is running by visiting http://localhost:9200 in a browser. If the response doesn't include version information formatted as JSON, you will need to troubleshoot your installation.

Download and configure Camunda

1. Download the latest release artifact in the Assets section of the release page, starting with 8.6.0-alpha2.
2. Navigate to the directory where you installed Camunda, and open /config/application.yaml. Add the following Elasticsearch exporter as a child of the zeebe/broker configuration element:

zeebe:
  broker:
    ...
    exporters:
      elasticsearch:
        className: io.camunda.zeebe.exporter.ElasticsearchExporter
        args:
          url: http://localhost:9200
          index:
            prefix: zeebe-record

note

Spacing is important! Indent the exporters element four spaces to properly nest the configuration.

Still need help?

Here is the full application.yaml file:

zeebe:
  broker:
    gateway:
      # Enable the embedded gateway to start on broker startup.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_ENABLE.
      enable: true

      network:
        # Sets the port the embedded gateway binds to.
        # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_NETWORK_PORT.
        port: 26500

      security:
        # Enables TLS authentication between clients and the gateway
        # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_SECURITY_ENABLED.
        enabled: false
        authentication:
          # Controls which authentication mode is active, supported modes are 'none' and 'identity'.
          # If 'identity' is set, authentication will be done using camunda-identity, which needs to
          # be configured in the corresponding subsection. See also https://docs.camunda.io/docs/self-managed/identity/what-is-identity/ .
          # This setting can also be overridden using the environment variable ZEEBE_BROKER_GATEWAY_SECURITY_AUTHENTICATION_MODE.
          mode: none

    network:
      # Controls the default host the broker should bind to. Can be overwritten on a
      # per-binding basis for client, management and replication
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_NETWORK_HOST.
      host: 0.0.0.0

    data:
      # Specify a directory in which data is stored.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_DIRECTORY.
      directory: data
      # The size of data log segment files.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_LOGSEGMENTSIZE.
      logSegmentSize: 128MB
      # How often we take snapshots of streams (time unit)
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_DATA_SNAPSHOTPERIOD.
      snapshotPeriod: 15m

    cluster:
      # Specifies the Zeebe cluster size.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_CLUSTERSIZE.
      clusterSize: 1
      # Controls the replication factor, which defines the count of replicas per partition.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_REPLICATIONFACTOR.
      replicationFactor: 1
      # Controls the number of partitions, which should exist in the cluster.
      # This can also be overridden using the environment variable ZEEBE_BROKER_CLUSTER_PARTITIONSCOUNT.
      partitionsCount: 1

    threads:
      # Controls the number of non-blocking CPU threads to be used.
      # WARNING: You should never specify a value that is larger than the number of physical cores
      # available. Good practice is to leave 1-2 cores for ioThreads and the operating
      # system (it has to run somewhere). For example, when running Zeebe on a machine
      # which has 4 cores, a good value would be 2.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_THREADS_CPUTHREADCOUNT
      cpuThreadCount: 2
      # Controls the number of io threads to be used.
      # This setting can also be overridden using the environment variable ZEEBE_BROKER_THREADS_IOTHREADCOUNT
      ioThreadCount: 2

    exporters:
      elasticsearch:
        className: io.camunda.zeebe.exporter.ElasticsearchExporter
        args:
          url: http://localhost:9200
          index:
            prefix: zeebe-record

camunda:
  # Operate configuration properties
  operate:
    # Set operate username and password.
    # If user with <username> does not exists it will be created.
    # Default: demo/demo
    #username:
    #password:
    # ELS instance to store Operate data
    elasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
    # Zeebe instance
    zeebe:
      # Gateway address
      gatewayAddress: localhost:26500
    # ELS instance to export Zeebe data to
    zeebeElasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
      # Index prefix, configured in Zeebe Elasticsearch exporter
      prefix: zeebe-record
  # Tasklist configuration properties
  tasklist:
    # Set Tasklist username and password.
    # If user with <username> does not exists it will be created.
    # Default: demo/demo
    #username:
    #password:
    # ELS instance to store Tasklist data
    elasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # URL
      url: http://localhost:9200
    # Zeebe instance
    zeebe:
      # Gateway address
      gatewayAdress: localhost:26500
    # ELS instance to export Zeebe data to
    zeebeElasticsearch:
      # Cluster name
      clusterName: elasticsearch
      # Url
      url: http://localhost:9200
      # Index prefix, configured in Zeebe Elasticsearch exporter
      prefix: zeebe-record

Save the file. Without performing this step, no data will be visible in Operate or Tasklist.

3. To start Camunda, run bin/camunda (or bin\camunda.bat on Windows).

It may take a few minutes for startup to complete. When the message Started StandaloneCamunda in ___ seconds is displayed, the application is ready to use.

tip

Operate can be found at http://localhost:8080/ and Tasklist can be found at http://localhost:8080/tasklist. Both use a default username/password of demo/demo.

SaaS

Have you signed up for Camunda yet?

Sign Up

Visit camunda.io/signup to sign up.

Create an account

Fill out the form and click Create account.

When you fill out the form, you'll receive a confirmation email. Click on the link to verify your email address.

Log in to your Camunda 8 account

Log in with the email address and password you used in the previous form, or use the social login buttons. To access the login site directly, navigate to camunda.io.

After login, select the square-shaped Camunda components icon in the upper-left corner, and select Console to view the Console overview page. This is the central place to manage the clusters, diagrams, and forms you want to deploy to Camunda 8.

Additionally, you need the following:

• Java >= 8
• Maven
• IDE (IntelliJ, VSCode, or similar)
• Download and unzip or clone the repo, then cd into camunda-platform-tutorials/orchestrate-microservices/worker-java

Step 1: Design your process with BPMN

Start by designing your automated process using BPMN. This guide introduces you to the palette and a few BPMN symbols in Web Modeler.

1. To create a BPMN diagram, click New project within Modeler.

2. Name your project and select Create new > BPMN diagram.

3. Give your model a descriptive name and id. On the right side of the page, expand the General section of the properties panel to find the name and id fields. For this guide, we'll use Microservice Orchestration Tutorial for the name and microservice-orchestration-tutorial for the id.

4. Use Web Modeler to design a BPMN process with service tasks. These service tasks are used to call your microservices via workers. Create a service task by dragging the task icon from the palette, or by clicking the existing start event and clicking the task icon. Make sure there is an arrow connecting the start event to the task. Click the wrench icon and select Service Task to change the task type.

5. Add a descriptive name using the General section in the properties panel. For this guide, we'll use Call Microservice.

6. In the properties panel, expand the Task definition section and use the Type field to enter a string used in connecting this service task to the corresponding microservice code. For this guide, we'll use orchestrate-something as the type. You will use this while creating a worker for the service task. If you do not have an option to add the Type, use the wrench icon and select Service Task.

   

7. Add an end event by dragging one from the palette, or by clicking the end event when the last service task in your diagram has focus. Make sure there is an arrow connecting the service task to the end event.

8. On the right upper corner click the blue Deploy button. Your diagram is now deployed to your cluster.

9. Start a new process instance by clicking on the blue Run button.

10. In the top left corner of the screen, click the square-shaped Camunda components button. Navigate to Operate to see your process instance with a token waiting at the service task by clicking View process instances.

Step 2: Create a cluster

To deploy and run your process, you must create a cluster in Camunda 8.

1. To create a cluster, navigate to Console by clicking the square-shaped icon labeled Camunda components in the top left corner, and click Console.
2. Click the Clusters tab, and click Create new cluster.
3. Name your cluster. For the purpose of this guide, we recommend using the Stable channel and the latest generation. Additionally, select your region. Click Create cluster.
4. Your cluster will take a few moments to create. Check the status on the Clusters page or by clicking into the cluster itself and looking at the Applications section.

Even while the cluster shows a status Creating, you can still proceed to begin modeling.

note

Zeebe must show a status of Healthy to properly deploy your model.

Development clusters

Starter Plan users have one development cluster, with free execution for development, included in their plan. Deployment and execution of models (process instances, decision instances, and task users) is provided at no cost. Additional clusters can be purchased through your billing reservations.

Visit the clusters page to learn more about the differences between development clusters and production clusters.

Step 3: Create credentials for your Zeebe client

To interact with your Camunda 8 cluster, you'll use the Zeebe client. First, you'll need to create credentials.

1. The main page for Console should be open on another tab. Use Console to navigate to your clusters either through the navigation Clusters or by using the section under View all on the Clusters section of the main dashboard. Click on your existing cluster. This will open the Overview for your cluster, where you can find your cluster id and region. You will need this information later when creating a worker in the next section.
   note

   If your account is new, you should have a cluster already available. If no cluster is available, or you’d like to create a new one, click Create New Cluster.

2. Navigate to the API tab. Click Create.
3. Provide a descriptive name for your client like microservice-worker. For this tutorial, the scope can be the default Zeebe scope. Click Create.
4. Your client credentials can be copied or downloaded at this point. You will need your client id and your client secret when creating a worker in the next section, so keep this window open. Once you close or navigate away from this screen, you will not be able to see them again.

Step 4: Create a worker for the service task

Next, we’ll create a worker for the service task by associating it with the type we specified on the service task in the BPMN diagram.

1. Open the downloaded or cloned project (repo, then cd into camunda-platform-tutorials/orchestrate-microservices/worker-java) in your IDE .
2. Add your credentials to application.properties. Your client id and client secret are available from the previous section in the credential text file you downloaded or copied. Go to the cluster overview page to find your cluster id and region.
3. In the Worker.java file, change the type to match what you specified in the BPMN diagram. If you followed the previous steps for this guide and entered “orchestrate-something”, no action is required.
4. After making these changes, perform a Maven install, then run the Worker.java main method via your favorite IDE. If you prefer using a terminal, run mvn package exec:java.
5. Using the Modeler tab in your browser, navigate to Operate and you will see your token has moved to the end event, completing this process instance.

Wrap up

Congratulations! You successfully built your first microservice orchestration solution with Camunda 8.

A core value of Camunda 8 lies in the flexibility offered to developers. You can write workers in many different languages. Camunda takes care of the orchestration.

Don't want to build the process yourself? Click this button to create it from a template in Camunda 8 SaaS, or sign up first.

Open model in Camunda 8Sign up

Additional resources and next steps

• Learn more about Camunda 8 and what it can do by reading What is Camunda 8 or watching our Overview video in Camunda Academy.
• Get your local environment ready for development with Camunda 8 by setting up your first development project.