Databases AWS

Hazelcast on AWS User Guide

| Product: Hazelcast on AWS

Overview

This image runs Hazelcast 5.7.0, the open source in-memory data grid and distributed compute platform. Hazelcast keeps data in RAM for memory-speed reads and writes, exposes distributed maps and other data structures, runs ANSI SQL over that in-memory data, and performs distributed compute - so applications get low-latency caching and fast data access without a disk round trip.

Hazelcast runs as a Java service on OpenJDK 17, under a dedicated unprivileged hazelcast system account, managed by a systemd unit that starts a single member on boot. The build ships the official open source slim distribution - the cleanly Apache-2.0-licensed core: the member, the SQL engine and the hz and hz-cli command line tools.

The member listener on port 5701 is bound to the loopback interface only. It is not reachable from the network, and the security group does not open it. This is a deliberate default: an in-memory grid with no built-in authentication should never be exposed to the internet. You reach the member over an SSH tunnel, or you rebind it to a private interface behind your own security group when you are ready. Both are covered below.

Hazelcast community edition has no password or TLS authentication realm - those are Enterprise features. Instead, the cluster name acts as a per-instance join secret: a client must present the exact cluster name to connect, and a client with any other cluster name is rejected at connect time. This image does not ship a shared one. A one-shot first-boot service generates a unique random cluster name on every instance, writes it into the member configuration before the member starts, and records it in /root/hazelcast-credentials.txt with mode 0600. The upstream default cluster name dev is rejected afterwards - this guide proves both directions below.

Because community edition is purely in-memory, persistence is not enabled and a fresh boot always starts an empty grid.

Prerequisites

Before you deploy this image you need:

  • An Amazon Web Services account where you can launch EC2 instances
  • IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
  • An EC2 key pair in the target Region for SSH access to the instance
  • A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network only
  • An SSH client on your workstation

You do not need to open port 5701 in the security group. The member is reached through the SSH tunnel described later in this guide.

Launching from the AWS Marketplace

  1. Open the product page in AWS Marketplace and choose Continue to Subscribe
  2. Accept the terms, then choose Continue to Configuration
  3. Select the software version and the Region you want to deploy into, then choose Continue to Launch
  4. Choose Launch through EC2 for full control of networking and storage
  5. Pick an instance type. m5.large is the recommended minimum; scale up as your working set and query concurrency grow, since Hazelcast is a JVM service that holds data in RAM and benefits from additional memory
  6. Select your VPC, subnet and key pair
  7. Attach a security group that allows inbound TCP 22 from your management network. Do not add a rule for 5701
  8. Launch, and wait for the instance to reach the 2/2 checks passed state

Launching with the AWS CLI

Substitute your own AMI id, key pair, security group and subnet:

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <your-sg-id> \
  --subnet-id <your-subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=hazelcast}]'

Connecting to your instance

Connect over SSH on port 22 as the default login user for the operating system variant you launched:

OS variant SSH login user
Ubuntu 24.04 LTS ubuntu 
ssh -i /path/to/your-key.pem ubuntu@<public-ip>

First boot takes a few moments to generate and apply the cluster join secret. If the credentials file still shows the placeholder text, wait a few seconds and read it again.

Verifying the member is running

Confirm the service is active and read the systemd status:

systemctl is-active hazelcast.service
systemctl status hazelcast.service --no-pager | sed -n '1,5p'

Real output from a deployed instance:

active
● hazelcast.service - Hazelcast member (cloudimg AWS Marketplace image)
     Loaded: loaded (/etc/systemd/system/hazelcast.service; enabled; preset: enabled)
     Active: active (running) since Wed 2026-07-22 04:10:09 UTC; 1min 7s ago
       Docs: https://www.cloudimg.co.uk/guides/hazelcast-aws/
   Main PID: 4686 (java)

Check the listening socket. It appears as the IPv4-mapped form [::ffff:127.0.0.1], which is the loopback address - the member is not reachable from the network:

ss -tln | grep 5701

LISTEN 0      100    [::ffff:127.0.0.1]:5701            *:*

Confirm the Hazelcast and Java versions:

/opt/hazelcast/bin/hz -V
java -version 2>&1 | sed -n '1p'

Version: 5.7.0
openjdk version "17.0.19" 2026-04-21

Retrieving the cluster join secret

The per instance cluster join secret is written to a root-only file on first boot:

sudo cat /root/hazelcast-credentials.txt

The file contains the generated cluster name along with the member host and port, this instance's public IP, and a reminder that the member is loopback only:

# Hazelcast - generated on first boot by hazelcast-firstboot.service
# The cluster name below is this VM's JOIN SECRET. A client must present it to
# connect; a client with any other cluster name is rejected. Keep it safe.

HAZELCAST_CLUSTER_NAME=<generated-on-first-boot>
HAZELCAST_HOST=127.0.0.1
HAZELCAST_MEMBER_PORT=5701
HAZELCAST_PUBLIC_IP=<this-instance-public-ip>

Load the cluster name into a shell variable rather than printing it, so it never lands in your shell history or terminal scrollback. The commands in the rest of this guide use $CL:

CL=$(sudo grep '^HAZELCAST_CLUSTER_NAME=' /root/hazelcast-credentials.txt | cut -d= -f2-)
if [ -n "$CL" ]; then echo "cluster join secret loaded (${#CL} characters)"; else echo "not yet generated"; fi

cluster join secret loaded (41 characters)

Confirm the file is readable only by root:

stat -c '%a %U:%G' /root/hazelcast-credentials.txt

600 root:root

Running an in-memory map with SQL

Open a SQL session against the member using the cluster name from the credentials file, create an in-memory map, insert a row and read it back. The round trip proves the grid is answering; the value comes back from RAM. The cluster name comes from $CL, so it is never echoed:

CL=$(sudo grep '^HAZELCAST_CLUSTER_NAME=' /root/hazelcast-credentials.txt | cut -d= -f2-)
printf '%s\n' \
  "CREATE OR REPLACE MAPPING demo TYPE IMap OPTIONS ('keyFormat'='int','valueFormat'='varchar');" \
  "SINK INTO demo (__key, this) VALUES (1, 'hello-hazelcast');" \
  "SELECT this FROM demo WHERE __key = 1;" \
  "DROP MAPPING demo;" \
  | timeout 60 /opt/hazelcast/bin/hz-cli sql -t "$CL@127.0.0.1:5701" 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep -vE '^Type .help|^Connected to Hazelcast|^$'

sql> OK
sql> OK
sql> +--------------------+
|this                |
+--------------------+
|hello-hazelcast     |
+--------------------+
1 row(s) selected
sql> OK
sql> Exiting from SQL console

A SELECT returning hello-hazelcast confirms the map was written to and read from the in-memory grid.

Confirming the join secret is unique to your instance

Community edition has no password realm, so the cluster name is the join secret. On this image it is rotated on first boot, so the upstream default dev must no longer connect. This check proves both directions - the generated cluster name is accepted, the default dev is rejected - without printing the secret:

CL=$(sudo grep '^HAZELCAST_CLUSTER_NAME=' /root/hazelcast-credentials.txt | cut -d= -f2-)
GOOD=$(printf 'SHOW MAPPINGS;\n' | timeout 20 /opt/hazelcast/bin/hz-cli sql -t "$CL@127.0.0.1:5701" 2>&1 | sed 's/\x1b\[[0-9;]*m//g' || true)
DEF=$(printf 'SHOW MAPPINGS;\n'  | timeout 15 /opt/hazelcast/bin/hz-cli sql -t 'dev@127.0.0.1:5701' 2>&1 | sed 's/\x1b\[[0-9;]*m//g' || true)
echo "$GOOD" | grep -q 'Connected to Hazelcast'               && echo "generated cluster name: ACCEPTED" || echo "generated cluster name: REJECTED"
echo "$DEF"  | grep -qiE 'authentication failed|does not match' && echo "default dev name:       REJECTED" || echo "default dev name:       ACCEPTED"

generated cluster name: ACCEPTED
default dev name:       REJECTED

If the second line ever reads ACCEPTED, the first boot rotation did not complete. Check systemctl status hazelcast-firstboot.service and contact cloudimg support.

Reaching the member from your workstation

Port 5701 is loopback only, so a Hazelcast client on your workstation reaches the member through an SSH tunnel. Open the tunnel from your workstation (not on the instance):

ssh -i /path/to/your-key.pem -L 5701:127.0.0.1:5701 ubuntu@<public-ip>

With the tunnel open, a client that connects to 127.0.0.1:5701 on your workstation is talking to the member. The client must be configured with the cluster name from the credentials file as its cluster name - this is the join secret. For example, with the Hazelcast CLI installed locally:

hz-cli sql -t '<your-cluster-name>@127.0.0.1:5701'

Connecting your application

Point your application's Hazelcast client at the member and set the cluster name to the join secret. In Java:

ClientConfig config = new ClientConfig();
config.setClusterName("<your-cluster-name>");
config.getNetworkConfig().addAddress("127.0.0.1:5701");   // through the SSH tunnel, or a private address
HazelcastInstance client = HazelcastClient.newHazelcastClient(config);
IMap<Integer, String> map = client.getMap("demo");
map.put(1, "hello-hazelcast");
System.out.println(map.get(1));

Clients in other languages (Python, .NET, Node.js, Go, C++) follow the same pattern: set the cluster name to the join secret and point the client at 127.0.0.1:5701 over the tunnel, or at the member's private address once you rebind it.

Network model and rebinding to a private interface

By default the member binds to 127.0.0.1 only. To make it reachable from other hosts in your VPC, edit the member configuration and replace the loopback interface, member list and public address with the instance's private IP, then restart the service:

sudo sed -i 's/127\.0\.0\.1/<private-ip>/g' /opt/hazelcast/config/hazelcast.yaml
sudo systemctl restart hazelcast.service

Only do this behind a security group that restricts port 5701 to trusted sources within your VPC. Community edition has no built-in authentication beyond the cluster-name join secret and no TLS, so never expose 5701 to the internet. When you rebind, keep the join secret confidential and treat it as the credential that it is.

Managing the service

The member is managed with systemd:

sudo systemctl status hazelcast.service     # current status
sudo systemctl restart hazelcast.service    # restart the member
sudo journalctl -u hazelcast.service -f     # follow the member log

The JVM heap is set conservatively in /etc/hazelcast/hazelcast-env.sh (JAVA_OPTS). On a larger instance, raise -Xmx there and restart the service so the grid can hold a larger working set.

Support

Every cloudimg deployment is backed by 24/7 support from cloudimg engineers by email at support@cloudimg.co.uk and by live chat, with a one-hour average response for critical issues. Support covers deployment and sizing, JVM heap tuning, cluster-name and join configuration, rebinding the member to a private interface, SSH tunnel and Hazelcast client connectivity, SQL and distributed-map usage, and Hazelcast upgrades and troubleshooting.

Hazelcast is a trademark of Hazelcast, Inc. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.