Hazelcast on Ubuntu 24.04 on Azure User Guide

Overview

Hazelcast is an open-source distributed in-memory data grid and compute platform. It keeps data in RAM for memory-speed reads and writes, exposes distributed maps and other data structures, runs ANSI SQL queries over that in-memory data, and executes distributed compute. This cloudimg image runs a single Hazelcast member built from the official open-source distribution. It installs Hazelcast 5.7.0 into /opt/hazelcast, runs it on OpenJDK 17 as a dedicated hazelcast system user, binds the member to 127.0.0.1 only, and rotates a unique cluster join secret on first boot. Management is via the bundled hz and hz-cli command-line tools and the SQL shell. Backed by 24/7 cloudimg support.

What is included:

• Hazelcast 5.7.0 from the official open-source (Apache-2.0 core) slim distribution, on OpenJDK 17
• A single member bound to 127.0.0.1 only, with the member port 5701 on loopback (not exposed publicly)
• A unique per-VM cluster join secret generated on first boot (no shared default credential)
• The default dev cluster name replaced, so only clients that present the per-VM secret can connect
• The hz-cli SQL shell for distributed SQL over in-memory maps
• 24/7 cloudimg support

This is an in-memory datastore product: Hazelcast listens on 127.0.0.1 only. There is no web console (Hazelcast Management Center is a separate product and is not shipped). The member port is not opened to the internet - connect locally on the VM or over an SSH tunnel.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + 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. NSG inbound: allow 22/tcp from your management network. No inbound application ports are needed because Hazelcast is reached 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 cloudimg, and select Create. On Basics 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 Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name hazelcast \
  --image <marketplace-image-urn> \
  --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

ssh azureuser@<vm-public-ip>

Step 4 - Confirm Hazelcast is installed and running

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

You should see the Hazelcast 5.7.0 version and active:

Version: 5.7.0
active

Step 5 - Confirm the member is bound to loopback only

Confirm 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. Remote access is via an SSH tunnel (Step 9).

Step 6 - Retrieve your per-VM cluster join secret

Hazelcast community edition uses the cluster name as its join credential: a client can only connect 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=cloudimg-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 this in your shell, substituting 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. The default dev cluster name is replaced with a unique per-VM value on first boot, so neither the default name nor any wrong name connects - only the per-VM cluster name in your credentials file works. You can see the rejection by attempting 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 - this 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/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 JVM options in /etc/hazelcast/hazelcast-env.sh, then 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 remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

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