How to Configure Hazelcast Clusters

How to Configure Hazelcast Clusters: Step-by-Step Guide

Hazelcast is a powerful in-memory data grid platform used for distributed computing, caching, and real-time processing. Configuring Hazelcast clusters properly is crucial to harness its full potential for scalability, fault tolerance, and performance. This tutorial provides a comprehensive guide on how to configure Hazelcast clusters, including prerequisites, configuration options, and troubleshooting tips.

Prerequisites

Basic knowledge of Java and distributed systems.
Java Development Kit (JDK) installed (version 8 or above recommended).
Access to multiple machines or virtual machines to simulate cluster nodes, or a local multi-instance setup.
Hazelcast library or Hazelcast IMDG downloaded from the Hazelcast official site (Official site).
Optional but recommended: Hazelcast Management Center for monitoring.

Step 1: Adding Hazelcast to Your Project

If you’re using Maven, add Hazelcast dependency to your pom.xml:

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>5.1.2</version> <!-- Use latest stable version -->
</dependency>

For Gradle users, add:

implementation 'com.hazelcast:hazelcast:5.1.2'

Step 2: Basic Hazelcast Configuration

The simplest way to start a Hazelcast instance is with default configuration in your Java code:

HazelcastInstance hz = Hazelcast.newHazelcastInstance();

This launches an instance that automatically looks for other Hazelcast instances on the network to form a cluster. However, for production and controlled environments, explicit configuration is better.

Configuring Using XML

Hazelcast supports XML-based configuration. Create a hazelcast.xml file like this:

<hazelcast xmlns="http://www.hazelcast.com/schema/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.hazelcast.com/schema/config
           http://www.hazelcast.com/schema/config/hazelcast-config-5.1.xsd">

    <network>
        <join>
            <multicast enabled="false"/>
            <tcp-ip enabled="true">
                <member>192.168.1.100:5701</member>
                <member>192.168.1.101:5701</member>
            </tcp-ip>
        </join>
    </network>

</hazelcast>

This disables multicast discovery and enables TCP/IP with explicit cluster member IP addresses, which is recommended for most environments to avoid unexpected node joining.

Step 3: Starting Multiple Cluster Nodes

You need to start Hazelcast instances on multiple machines or multiple JVMs with the same configuration for a clustered setup.

Copy hazelcast.xml to each node’s classpath.
Start each node using:

HazelcastInstance hz = Hazelcast.newHazelcastInstance();

Each node will now connect to others at the configured IP addresses and form a cluster.

Step 4: Configuring Cluster Group Name and Password (Security)

By default, Hazelcast uses a group name and password to isolate clusters:

<group>
    <name>dev</name>
    <password>dev-pass</password>
</group>

Add this inside your hazelcast.xml to prevent unauthorized nodes from joining your cluster.

Step 5: Advanced Network Configuration

Hazelcast supports multiple network-related settings for tuning cluster behavior:

Port Configuration: Default port 5701, range 5701–5801.
Interfaces: Bind Hazelcast nodes to specific local network interfaces.
SSL/TLS: For secure node-to-node communication.
Member Attributes: Assign attributes to filter members for specific tasks.

Example snippet to set explicit bind address and port:

<network>
    <port auto-increment="true" port-count="100" port="5701"/>
    <interfaces enabled="true">
        <interface>192.168.1.100</interface>
    </interfaces>
</network>

Step 6: Using Hazelcast Management Center

Hazelcast Management Center (Official site) is a web application that monitors and manages your cluster in real-time. Connect your cluster nodes to the Management Center by specifying the URL in the configuration or passing it as a JVM parameter.

Step 7: Troubleshooting Tips

Nodes don’t form cluster: Check network connectivity, firewall rules, and ensure TCP/IP join is enabled with correct IPs.
Ports already in use: Change the port or enable auto-increment as shown above.
Cluster split-brain: Use Hazelcast split-brain protection strategies.
High latency or slow join: Optimize network settings and JVM heap sizes.

Summary Checklist

Install JDK and Hazelcast library.
Create consistent hazelcast.xml configuration for cluster nodes.
Enable TCP/IP join with correct member IP addresses.
Set secure group name and password for cluster isolation.
Start Hazelcast instances on multiple nodes.
Use Hazelcast Management Center for monitoring.
Monitor logs and network to troubleshoot issues.

For a broader perspective on installing distributed systems, you might find our guide on how to install Ignite Database useful as an additional resource on clustering technologies.

Configuring Hazelcast clusters properly can significantly improve your application’s performance and scalability in distributed environments. With this tutorial, you now have the foundational steps to set up and manage a robust Hazelcast cluster.