Hazelcast for Kubernetes

See something wrong? Edit this page.

This sample is a guideline on how to start and use Hazelcast cluster in Kubernetes.

You can see the whole project here.

What You’ll Learn

In this guide, you will deploy Hazelcast cluster to Kubernetes and connect it to a Kubernetes application.


Deploy Hazelcast cluster

There are different ways of deploying Hazelcast to Kubernetes. For the production environment we recommend Helm or Hazelcast Operator because these methods provide the complete Hazelcast experience, including the following aspects:

  • Automated deployment including the Hazelcast Management Center tool

  • Automated lifecycle operations (scaling, upgrades) to avoid data loss

  • Role-based access control

  • Helm

  • Hazelcast Operator

  • Kubectl

helm repo add hazelcast https://hazelcast-charts.s3.amazonaws.com/
helm repo update
helm install hz-hazelcast hazelcast/hazelcast
kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/operator-rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcast-rbac.yaml
kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcastcluster.crd.yaml
kubectl --validate=false apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/operator.yaml
kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcast.yaml
kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-kubernetes/master/rbac.yaml

kubectl run hz-hazelcast-0 --image=hazelcast/hazelcast:$HAZELCAST_VERSION -l "role=hazelcast"
kubectl run hz-hazelcast-1 --image=hazelcast/hazelcast:$HAZELCAST_VERSION -l "role=hazelcast"
kubectl run hz-hazelcast-2 --image=hazelcast/hazelcast:$HAZELCAST_VERSION -l "role=hazelcast"

kubectl create service clusterip hz-hazelcast --tcp=5701 -o yaml --dry-run=client | kubectl set selector --local -f - "role=hazelcast" -o yaml | kubectl create -f -

You can check that the Hazelcast cluster is up and running.

kubectl logs hz-hazelcast-0
Members {size:3, ver:3} [
        Member []:5701 - 6d2100e0-8dcf-4e7c-ab40-8e98e23475e3 this
        Member []:5701 - 5ab4d554-fd7d-4929-8475-0ddf79a21076
        Member []:5701 - 7f7dd5f4-e732-4575-89d6-a6e823da38da

At this point you have started a Hazelcast cluster with 3 members. It is exposed with a service called hz-hazelcast.

Configure Hazelcast client

Use Hazelcast client to connect to the running Hazelcast cluster from your applications.

To use Hazelcast client, add Hazelcast client dependency to your application.

  • Java

  • NodeJS

  • Python

npm install hazelcast-client
pip install hazelcast-python-client

Configure the Hazelcast client in your application to connect to the hz-hazelcast service.

  • Java

  • NodeJS

  • Python

ClientConfig config = new ClientConfig();

// Additionally configure connection retry timout
const { Client } = require('hazelcast-client');

const clientConfig = {
    network: {
        clusterMembers: [
const client = await Client.newHazelcastClient(clientConfig);
import hazelcast

client = hazelcast.HazelcastClient(

Your application is now configured to automatically connect to the Hazelcast cluster once it’s deployed to Kubernetes.

Deploy client application

To deploy your application to Kubernetes cluster, you need first to dockerize it.

  • Java

  • NodeJS

  • Python

docker build -t hazelcastguides/hazelcast-client java
docker build -t hazelcastguides/hazelcast-client nodejs
docker build -t hazelcastguides/hazelcast-client python

If you use a remote Kubernetes cluster and you want to build your own Docker image then make sure that you also push your Docker image into the Docker registry.

kubectl run hazelcast-client --image=hazelcastguides/hazelcast-client

After a moment, check application logs to see it running in Kubernetes.

kubectl logs hazelcast-client
Members {size:3, ver:3} [
        Member []:5701 - 6d2100e0-8dcf-4e7c-ab40-8e98e23475e3 this
        Member []:5701 - 5ab4d554-fd7d-4929-8475-0ddf79a21076
        Member []:5701 - 7f7dd5f4-e732-4575-89d6-a6e823da38da
Successful connection!
Starting to fill the map with random entries.
Current map size: 71754
Current map size: 71758
Current map size: 71782
Current map size: 71792

To remove the client application, execute the following command.

kubectl delete pod hazelcast-client

Tear down Hazelcast cluster

To delete Hazelcast cluster, run the following commands.

  • Helm

  • Hazelcast Operator

  • Kubectl

helm uninstall hz-hazelcast
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcast.yaml
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/operator.yaml
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcastcluster.crd.yaml
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/hazelcast-rbac.yaml
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-operator/master/hazelcast-operator/operator-rbac.yaml
kubectl delete service hz-hazelcast
kubectl delete pod hz-hazelcast-0 hz-hazelcast-1 hz-hazelcast-2
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast-kubernetes/master/rbac.yaml