Broadleaf Microservices
  • v1.0.0-latest-prod

Camel Cluster Service


Certain services within the Broadleaf ecosystem utilize the concept of a cluster singleton pattern to ensure that you have exactly one instance of a particular node in a cluster responsible for executing a specific piece of functionality.

Some examples that employ this pattern include:

  • Broadleaf’s Messaging Resiliency: See the Durable Send characteristics that are included with Broadleaf’s Messaging Components for more details.

  • Scheduled Job Co-ordination: To ensure a trigger event is only emitted once, the Scheduled Job Service should be configured to operate as a singleton in a cluster. See the Clustering Components section of the Scheduled Job Service for more details.

Camel Cluster Service

In order to accomplish this cluster singleton pattern, Broadleaf employs the use of Apache’s CamelClusterService allowing you to configure a number of backing Cluster SPI implementations out-of-the-box (e.g. Kubernetes, Zookeeper, File-based, etc…​)

Broadleaf provides example configuration and support for the following implementations:

  • org.apache.camel.component.file.cluster.FileLockClusterServic

  • org.apache.camel.component.kubernetes.cluster.KubernetesClusterService

See the following classes for more details:

  • com.broadleafcommerce.common.messaging.environment.MessagingProperties which is documented here

  • com.broadleafcommerce.scheduledjob.service.autoconfigure.ClusterProperties which is documented here

FileLockClusterService (Local)

Broadleaf services by default have the FileLockClusterService implementation configured. This is suitable for LOCAL development outside the use of Kubernetes.

You may notice the following WARNING emitted to your logs if the system is still configured to use file on a non-local environment:

***** WARNING - broadleaf.messaging.cluster-service-implementation-type is set to `file`. This prevents cluster detection beyond a single node, which is only appropriate for local development. This value should be changed to `kubernetes` or `zookeeper` (usually `kubernetes` via manifest environment variable when deploying to k8s). *****
As of Broadleaf 1.5.x, we have deprecated the use of org.apache.camel.component.jgroups.cluster.JGroupsLockClusterService as the default (in favor of the FileLockClusterService). While JGroups might be an adequate solution for some setups, there is some significant configuration that would need to be done to fully support it. JGroups utilizes UDP Multi-casting to achieve communication between the nodes. This mechanism is not fully supported in a lot of cloud environments without additional networking configuration and setup. Instead, we recommend configuring the KubernetesClusterService or the ZooKeeperClusterService for non-local deployments

KubernetesClusterService (Non-Local)

As we provide the a lot of support for deploying the Microservices stack to a Kubernetes cluster, it makes sense to utilize Kubernetes’s built in APIs to co-ordinate leader/member setups within replicas in a cluster using Apache’s default org.apache.camel.component.kubernetes.cluster.KubernetesClusterService.

In order to tell Broadleaf to change from a File-based implementation to a Kubernetes-based implementation, you can pass in the following ENV overrides in your deployment:


  • BROADLEAF_MESSAGING_CLUSTERK8SAPPLABELVALUE: <unique name for each deployment> (e.g. auth, browse, cart, processing, or supporting if deploying the Balanced Flex Package Composition or cart, catalog, campaign, etc…​ if deploying the Granular Composition)

  • LOGGING_LEVEL_ORG_APACHE_CAMEL_COMPONENT_KUBERNETES_CLUSTER_LOCK: WARN (optional, but helpful to debug any connectivity issues)

Our default Helm charts are already configured to supply the necessary ENV overrides to switch the CamelClusterService to use Kubernetes instead of the default File based implementation