Get Started

Get Started

These guides demonstrate how to get started quickly with Hazelcast IMDG and Hazelcast Jet.

Hazelcast IMDG

Learn how to store and retrieve data from a distributed key-value store using Hazelcast IMDG. In this guide you’ll learn how to:

  • Create a cluster of 3 members.
  • Start Hazelcast Management Center
  • Add data to the cluster using a sample client in the language of your choice
  • Add and remove some cluster members to demonstrate data balancing capabilities of Hazelcast

Hazelcast Jet

Learn how to build a distributed data processing pipeline in Java using Hazelcast Jet. In this guide you’ll learn how to:

  • Install Hazelcast Jet and form a cluster on your computer
  • Build a simple pipeline that receives a stream of data, does some calculations and outputs some results
  • Submit the pipeline as a job to the cluster and observe the results
  • Scale the cluster up and down while the job is still running

How to Set Up Hazelcast IMDG on AWS ECS

December 12, 2018

Amazon ECS (Elastic Container Service) is a container orchestration service that supports Docker containers. It allows to create scalable clusters backed up by EC2 Instances. Hazelcast IMDG is distributed in a form of Docker Image and provides the plugin for auto discovery in the AWS environment, therefore it can be simply configured to work on AWS ECS. This post presents this process step-by-step and the source code for this example can be found here.

Step 1: Create AWS ECS Cluster

First, you need a working AWS ECS Cluster. To create it, open AWS ECS Console: Select “Clusters” and “Create Cluster.” Choose “EC2 Linux + Networking” and click “Next Step.”

Note the following fields as you’ll need them later for the Hazelcast configuration:

  • Cluster name
  • VPC CIDR block

You may also want to set “Security group inbound rules” to allow access to your application from outside AWS.

Step 2: Configure Hazelcast to work on AWS ECS

You can configure Hazelcast to work on AWS using the hazelcast-aws plugin.

Add the following Maven dependencies:


Then, configure the AWS Discovery Strategy properties. You can do it in two different manners: Java-based configuration or XML configuration. In the code sample, we used the first approach:

public Config hazelcastConfig() {
    Config config = new Config();
    JoinConfig joinConfig = config.getNetworkConfig().getJoin();
              .setProperty("region", "eu-central-1")
              .setProperty("tag-key", "aws:cloudformation:stack-name")
              .setProperty("tag-value", "EC2ContainerService-test-cluster");
    return config;

The equivalent XML configuration would look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<hazelcast xmlns="" xmlns:xsi="" xsi:schemaLocation=" hazelcast-config-3.11.xsd">
    <interfaces enabled="true">
      <multicast enabled="false"/>
      <aws enabled="true">

Note the following parameters:

  • interface: must be the same as “VPC CIDR block”
  • region: must the same as the region in which your cluster is running
  • tag-key, tag-value: ECS automatically tags EC2 instances, so you can use the tags (change “test-cluster” to the name of your cluster); if you don’t specify “tag-key” and “tag-value,” then all your EC2 Instances will be used to form the Hazelcast cluster.

Step 3: Build application and Docker image

Now, you need to build the application and publish it as a Docker image. You can use the standard “docker build” and “docker push” commands, however if you follow the source code mentioned at the beginning, you may just execute the following command which compiles the project, builds the Docker image and pushes it into your Docker Hub account.

mvn clean compile jib:build -Dimage=leszko/aws-ecs-sample

Please change “leszko” to your Docker Hub login. Then, make sure that your image in Docker Hub is public (you can do it on the Docker Hub website).

Step 4: Create AWS ECS Task Definition

Open the AWS ECS Console again and click on “Task Definitions” and “Create new Task Definition.” Select “EC2” and click “Next Step.”

Fill the required fields. Don’t forget to set “Network Mode” to “Host” (that is the only network mode currently supported by the Hazelcast AWS Plugin).

Click “Add container” and fill the required fields.

Add logging to the container specification.

Click “Add” and “Create” and your task definition is created.

Step 5: Start AWS ECS Service

Open your cluster and in the tab “Services,” click “Create.”

Select your task definition and the number of tasks. Click “Next step” a few times and “Create.”

Your service with tasks should be running.

Step 6: Verify that the Application works correctly

Click on any of the running tasks and scroll down to the “Log Configuration” section.

Click “View logs in CloudWatch.” You should see that the Hazelcast Members formed one cluster.


Hazelcast supports automatic members discovery on AWS ECS, however currently you’re limited to use the “host” network. This implies that you also have to explicitly specify the network interface pattern. Note that you can use the AWS Discovery plugin for the member-to-member discovery, as well as client-to-member discovery. This allows you to use Hazelcast in both architectures: embedded mode and client-server mode.

About the Author

About the Author

Rafal Leszko

Rafal Leszko

Cloud Software Engineer

Rafał is a passionate software engineer, trainer, conference speaker, and author of the book, Continuous Delivery with Docker and Jenkins. He specializes in Java development, cloud environments, and continuous delivery. Prior to joining Hazelcast, Rafał worked with a variety of companies and scientific organizations, including Google, CERN, and AGH University of Science and Technology.

Latest Blogs

Securing Hazelcast with Cert-Manager

Securing Hazelcast with Cert-Manager

How to Set Up Your Own On-Premises Hazelcast on Kubernetes

How to Set Up Your Own On-Premises Hazelcast on Kubernetes

Hazelcast Resilient to Kubernetes Zone Failures

Hazelcast Resilient to Kubernetes Zone Failures

View all blogs by the author
Open Gitter Chat