Deploy Hazelcast using Kubernetes

Hazelcast now offers the Hazelcast Platform Operator. We recommend using this operator when working with Hazelcast in Kubernetes. For more info, see Connect External Hazelcast Client to Kubernetes.

What You’ll Learn

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

Before you Begin

Up and running Kubernetes cluster (version 1.9 or higher)
Kubernetes command line tool, kubectl
(optional) Helm CLI

Deploy Hazelcast cluster

There are different ways of deploying Hazelcast to Kubernetes. For the production environment we recommend Hazelcast Platform Operator or Helm 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 Platform Operator
Kubectl

helm repo add hazelcast https://hazelcast-charts.s3.amazonaws.com/
helm repo update
helm install hz-hazelcast hazelcast/hazelcast

helm repo add hazelcast https://hazelcast-charts.s3.amazonaws.com/
helm repo update
helm install operator hazelcast/hazelcast-platform-operator --set installCRDs=true
cat << EOF | kubectl apply -f -
apiVersion: hazelcast.com/v1alpha1
kind: Hazelcast
metadata:
  name: hz-hazelcast
EOF

kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast/master/kubernetes-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 [10.216.6.7]:5701 - 6d2100e0-8dcf-4e7c-ab40-8e98e23475e3 this
        Member [10.216.5.6]:5701 - 5ab4d554-fd7d-4929-8475-0ddf79a21076
        Member [10.216.8.6]: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
C++
Go

pom.xml

<dependency>
    <groupId>com.hazelcast</groupId>
    <artifactId>hazelcast</artifactId>
    <version>${hazelcast.version}</version>
</dependency>

npm install hazelcast-client

pip install hazelcast-python-client

curl -Lo hazelcast-cpp-client.tar.gz https://github.com/hazelcast/hazelcast-cpp-client/archive/v${VERSION}.tar.gz
tar xzf hazelcast-cpp-client.tar.gz

go get github.com/hazelcast/hazelcast-go-client@v1.0.0

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

Java
NodeJS
Python
C++
Go

ClientConfig config = new ClientConfig();
config.getNetworkConfig().addAddress("hz-hazelcast");

const { Client } = require('hazelcast-client');

const clientConfig = {
    network: {
        clusterMembers: [
            'hz-hazelcast'
        ]
    }
};
const client = await Client.newHazelcastClient(clientConfig);

import hazelcast

client = hazelcast.HazelcastClient(
    cluster_members=["hz-hazelcast"],
)

#include <hazelcast/client/hazelcast_client.h>

hazelcast::client::client_config config;
config.get_network_config()
      .add_address({"hz-hazelcast", 5701})
auto hz = hazelcast::new_client(std::move(config)).get();

import (
	"log"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	config := hazelcast.Config{}
	config.Cluster.Network.SetAddresses("hz-hazelcast:5701")
	ctx := context.Background()
	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
    if err != nil {
        log.Fatal(err)
    }
}

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
C++
Go

docker build -t hazelcastguides/hazelcast-client java

docker build -t hazelcastguides/hazelcast-client nodejs

docker build -t hazelcastguides/hazelcast-client python

docker build -t hazelcastguides/hazelcast-client cpp

docker build -t hazelcastguides/hazelcast-client go

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 [10.216.6.7]:5701 - 6d2100e0-8dcf-4e7c-ab40-8e98e23475e3 this
        Member [10.216.5.6]:5701 - 5ab4d554-fd7d-4929-8475-0ddf79a21076
        Member [10.216.8.6]: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 Platform Operator
Kubectl

helm uninstall hz-hazelcast

kubectl delete hazelcast hz-hazelcast
helm uninstall operator

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/master/kubernetes-rbac.yaml