Hazelcast for Kubernetes

Hazelcast now offers the Hazelcast Platform Operator. We recommend using this operator when working with Hazelcast in Kubernetes. See Connect To Hazelcast Running on Kubernetes from Outside.

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

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

See Also