Hazelcast

Prerequisites

• An active Azure subscription, an SSH key pair, and a virtual network and subnet in the target region.
• Standard_B4ms (4 vCPU, 16 GiB RAM) is a good starting point, because Hazelcast is an in-memory grid and benefits from RAM.
• A network security group that allows inbound 22/tcp from your management network. No inbound application ports are needed, because you reach Hazelcast over the SSH tunnel.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Hazelcast by SecureAnyCloud, and select Create. On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) only. Then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

To deploy from the command line instead, run the following commands:

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:hazelcast-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name hazelcast \
  --image sac1647283583153:hazelcast-ubuntu-24-04:default:latest \
  --size Standard_B4ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

Connect over SSH with your key pair:

ssh azureuser@<vm-public-ip>

Step 4 - Confirm Hazelcast is installed and running

Check the installed version and the service state:

/opt/hazelcast/bin/hz -V systemctl is-active hazelcast

The output shows the Hazelcast 5.7.0 version and active:

Version: 5.7.0 active

Step 5 - Confirm the member is bound to loopback only

Confirm that the member port 5701 is listening on 127.0.0.1 only and is not exposed on any external interface:

ss -tln | grep 5701

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

The member binds to 127.0.0.1, so the cluster protocol port 5701 is not reachable from outside the VM. Use an SSH tunnel for remote access (Step 9).

Step 6 - Retrieve your per-VM cluster join secret

Hazelcast community edition uses the cluster name as its join credential, so a client can connect only if it presents the same cluster name as the member. Each VM generates its own unique cluster name on first boot and writes it to a root-only credentials file:

sudo cat /root/hazelcast-credentials.txt

The file looks like this (your value is unique to your VM):

HAZELCAST_CLUSTER_NAME=sac-3f9a1c8e5b2d4a7f6c0e9b8a1d2f3e4c HAZELCAST_HOST=127.0.0.1 HAZELCAST_MEMBER_PORT=5701 HAZELCAST_PUBLIC_IP=20.55.10.20

Store the cluster name in your secrets manager. In the steps below, <HAZELCAST_CLUSTER_NAME> stands for the value of HAZELCAST_CLUSTER_NAME.

Step 7 - Run SQL with hz-cli

Hazelcast ships a SQL shell, hz-cli sql. Connect by passing your per-VM cluster name and the loopback address as the target. Run the following command in your shell and substitute the real cluster name for <HAZELCAST_CLUSTER_NAME>:

/opt/hazelcast/bin/hz-cli sql -t '<HAZELCAST_CLUSTER_NAME>@127.0.0.1:5701'

At the sql> prompt you can create a mapping over an in-memory map, insert rows and query them:

Connected to Hazelcast 5.7.0 at [127.0.0.1]:5701 (+0 more) Type 'help' for instructions sql> CREATE MAPPING cities TYPE IMap OPTIONS ('keyFormat'='int','valueFormat'='varchar'); OK sql> SINK INTO cities (__key, this) VALUES (1,'London'),(2,'Paris'),(3,'Tokyo'); OK sql> SELECT __key, this FROM cities ORDER BY __key; +------------+--------------------+ | __key|this | +------------+--------------------+ | 1|London | | 2|Paris | | 3|Tokyo | +------------+--------------------+ 3 row(s) selected sql>

Step 8 - The authentication wall

The cluster name is the join secret. First boot replaces the default dev cluster name with a unique per-VM value, so neither the default name nor any wrong name connects. Only the per-VM cluster name in your credentials file works. To see the rejection, attempt a connection with a wrong cluster name. The connection is refused with an authentication error, while the per-VM cluster name from Step 6 connects successfully:

$ /opt/hazelcast/bin/hz-cli sql -t 'wrong-cluster@127.0.0.1:5701' com.hazelcast.client.AuthenticationException: Authentication failed. The configured cluster name on the client does not match the one configured in the cluster or the credentials set in the Client security config could not be authenticated

Step 9 - Connect remotely over an SSH tunnel

Hazelcast listens on 127.0.0.1 only (port 5701) and is not exposed publicly, which is the secure default. To reach the member from your workstation, open an SSH tunnel and point a local Hazelcast client (or a local hz-cli) at localhost:5701:

# On your workstation:
ssh -L 5701:127.0.0.1:5701 azureuser@<vm-public-ip>
# In another terminal, point a Hazelcast client / hz-cli at:
# -t '<HAZELCAST_CLUSTER_NAME>@127.0.0.1:5701'

For production remote access without a tunnel, bind Hazelcast to a private NIC and front it with TLS. TLS and password or LDAP auth realms are Hazelcast Enterprise features. Never expose 5701 to the internet without transport encryption.

Maintenance

• Data: Hazelcast community edition is in-memory. The grid starts empty on every boot, and data does not survive a full restart. For durable persistence, use the Hazelcast Enterprise Persistence feature or write through to a backing datastore.
• Cluster join secret: rotate it by editing cluster-name in /opt/hazelcast/config/hazelcast.yaml and running sudo systemctl restart hazelcast. Then update your credentials store.
• Configuration: edit /opt/hazelcast/config/hazelcast.yaml (network, ports, data structures) and the JVM options in /etc/hazelcast/hazelcast-env.sh, then run sudo systemctl restart hazelcast.
• Logs: the member logs to /var/log/hazelcast/hazelcast.log and to the systemd journal (sudo journalctl -u hazelcast).
• Security patches: unattended-upgrades stays enabled, so the OS keeps receiving security updates automatically.

Support

SecureAnyCloud provides 24/7 expert support for this image. Contact sales@secureanycloud.com.

Hazelcast is a trademark of Hazelcast, Inc. This image is provided by SecureAnyCloud and is not affiliated with or endorsed by Hazelcast, Inc. Hazelcast Management Center and Hazelcast Enterprise are separate products and are not included.

Deploy on Azure

Launch Hazelcast on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

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 that allows 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. You reach the member through the SSH tunnel described later in this guide.

Launching from the AWS Marketplace

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

Launching with the AWS CLI

Run the following command, and 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 does not yet show a cluster name, 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 (sac 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://secureanycloud.com/stacks/hazelcast/ 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, so 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

First boot writes the per-instance cluster join secret to a root-only file:

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 with the cluster name from the credentials file, create an in-memory map, insert a row and read it back. The round trip shows that the grid is answering, and 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. First boot rotates it, so the upstream default dev must no longer connect. This check verifies both directions without printing the secret. The generated cluster name is accepted, and the default dev is rejected:

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 SecureAnyCloud 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. Configure the client with the cluster name from the credentials file as its cluster name, because that name 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, use:

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, replace the loopback interface, member list and public address with the instance's private IP, and restart the service:

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

Do this only 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 that the grid can hold a larger working set.

Support

Every SecureAnyCloud deployment is backed by 24/7 support from SecureAnyCloud engineers by email at sales@secureanycloud.com 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.

Deploy on AWS

Launch Hazelcast on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com