Deploy Hazelcast using Kubernetes

note

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 later)
• Kubernetes command line tool, kubectl
• (optional) Helm CLI

Deploy Hazelcast cluster

There are different ways of deploying Hazelcast to Kubernetes. For production environments, we recommend using 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

bash

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

Hazelcast Platform Operator

bash

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

bash

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.

bash

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

pom.xml

xml

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

NodeJS

bash

npm install hazelcast-client

Python

bash

pip install hazelcast-python-client

C++

bash

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

bash

go get github.com/hazelcast/[email protected]

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

Java

java

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

NodeJS

javascript

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

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

Python

python

import hazelcast

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

C++

cpp

#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();

Go

go

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

bash

docker build -t hazelcastguides/hazelcast-client java

NodeJS

bash

docker build -t hazelcastguides/hazelcast-client nodejs

Python

bash

docker build -t hazelcastguides/hazelcast-client python

C++

bash

docker build -t hazelcastguides/hazelcast-client cpp

Go

bash

docker build -t hazelcastguides/hazelcast-client go

note

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.

bash

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

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

bash

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.

bash

kubectl delete pod hazelcast-client

Tear down Hazelcast cluster

To delete Hazelcast cluster, run the following commands.

Helm

bash

helm uninstall hz-hazelcast

Hazelcast Platform Operator

bash

kubectl delete hazelcast hz-hazelcast
helm uninstall operator

kubectl

bash

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

• Deploy Hazelcast Cluster with Kubernetes HPA
• Connect External Hazelcast Client to Kubernetes
• Use Hazelcast as Sidecar Container