Connect to Hazelcast from Outside Kubernetes

What You’ll Learn

In this tutorial, you’ll connect to a Hazelcast cluster running in Kubernetes from outside of the Kubernetes environment.

Before you Begin

Introduction

There are two available options for Expose Externally feature of Hazelcast Platform Operator:

  • Unisocket - client requests are load balanced between Hazelcast members.

  • Smart - client connects to all members and sends requests directly to the members owning the data.

Let’s see both approaches.

Unisocket

The first option is to use the Unisocket type. This option will use the standard Kubernetes mechanism that automatically load balances the traffic to Hazelcast members.

Hazelcast Unisocket Client
Figure 1. Hazelcast Unisocket Client

Start the Hazelcast Cluster

Run the following command to create the Hazelcast cluster with Expose Externally feature enabled using Unisocket type.

cat <<EOF | kubectl apply -f -
apiVersion: hazelcast.com/v1alpha1
kind: Hazelcast
metadata:
  name: my-hazelcast
spec:
  exposeExternally:
    type: Unisocket
    discoveryServiceType: LoadBalancer
EOF

For discoveryServiceType you can use:

  • LoadBalancer - will create an external LoadBalancer for discovery serivce;

  • NodePort - will expose the discovery service via NodePort.

Verify the Hazelcast Cluster

Check the cluster status by running the following command.

$ kubectl get hazelcast my-hazelcast
NAME        STATUS    MEMBERS
hazelcast   Running   3/3

After verifying that the cluster is Running and all the members are ready (3/3), run the following command to find the discovery service address.

$ kubectl get service my-hazelcast
NAME           TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)          AGE
my-hazelcast   LoadBalancer   10.43.240.23   35.240.113.74   5701:30218/TCP   65s

The field EXTERNAL-IP is the address of your Hazelcast cluster.

Connect Hazelcast Clients to the Cluster

Configure the Hazelcast client with the external address and disable smart routing to use the unisocket connection.

  • Java

  • NodeJS

  • Go

  • Python

ClientConfig config = new ClientConfig();
config.getNetworkConfig().addAddress("<EXTERNAL-IP>")
                         .setSmartRouting(false);
const { Client } = require('hazelcast-client');

const clientConfig = {
    network: {
        clusterMembers: [
            '<EXTERNAL-IP>'
        ],
        smartRouting: false
    }
};
const client = await Client.newHazelcastClient(clientConfig);
import (
	"log"

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

func main() {
	config := hazelcast.Config{}
	cc := &config.Cluster
	cc.Network.SetAddresses("<EXTERNAL-IP>")
	cc.Unisocket = true
	ctx := context.TODO()
	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
	if err != nil {
		panic(err)
	}
}
import logging
import hazelcast

logging.basicConfig(level=logging.INFO)

client = hazelcast.HazelcastClient(
    cluster_members=["<EXTERNAL-IP>"],
    use_public_ip=True,
    smart_routing=False,
)

Now you can start the application.

  • Java

  • NodeJS

  • Go

  • Python

cd java-unisocket
mvn package
java -jar target/*jar-with-dependencies*.jar
cd nodejs-unisocket
npm install
npm start
cd go-unisocket
go run main.go
cd python-unisocket
pip install -r requirements.txt
python main.py

You should see the following output.

Successful connection!
Starting to fill the map with random entries.
Current map size: 2
Current map size: 3
Current map size: 4
Current map size: 5
Current map size: 6
Current map size: 7
Current map size: 8
Current map size: 9
Current map size: 10

Smart Client

The second option is to use the Smart type. With this option, each Hazelcast member will be exposed with its own service (it can be either LoadBalancer or NodePort). Hazelcast smart client is capable of mapping the given key with its owner member, which means that it sends the data directly to the member which contains the right data partition.

Hazelcast Smart Client
Figure 2. Hazelcast Smart Client

Start the Hazelcast Cluster

Run the following command to create the Hazelcast cluster with Expose Externally feature enabled using Smart type.

cat <<EOF | kubectl apply -f -
apiVersion: hazelcast.com/v1alpha1
kind: Hazelcast
metadata:
  name: my-hazelcast
spec:
  exposeExternally:
    type: Smart
    discoveryServiceType: LoadBalancer
    memberAccess: LoadBalancer
EOF

This will create the Hazelcast cluster and one LoadBalancer service for discovery and one LoadBalancer service for each pod.

For discoveryServiceType you can use:

  • LoadBalancer - will create an external LoadBalancer for discovery serivce;

  • NodePort - will expose the discovery service via NodePort.

For memberAccess you can use the following options:

  • LoadBalancer - lets the client access Hazelcast member with the LoadBalancer service;

  • NodePortNodeName - lets the client access Hazelcast member with the NodePort service and the node name;

  • NodePortExternalIP - lets the client access Hazelcast member with the NodePort service and the node external IP/hostname.

Verify the Hazelcast Cluster

Check the cluster status by running the following command.

$ kubectl get hazelcast my-hazelcast
NAME        STATUS    MEMBERS
hazelcast   Running   3/3

After verifying that the cluster is Running and all the members are ready (3/3), run the following command to find the discovery service address.

$ kubectl get service my-hazelcast
NAME           TYPE           CLUSTER-IP       EXTERNAL-IP       PORT(S)          AGE
hz-hazelcast   LoadBalancer   10.108.141.178   10.96.184.178     5701:31434/TCP   5m44s

The field EXTERNAL-IP is the address of your Hazelcast cluster.

Connect Hazelcast Clients to the Cluster

Configure the Hazelcast client to connect to the cluster external address.

  • Java

  • NodeJS

  • Go

  • Python

ClientConfig config = new ClientConfig();
config.getNetworkConfig().addAddress("<EXTERNAL-IP>");
const { Client } = require('hazelcast-client');

const clientConfig = {
    network: {
        clusterMembers: [
            '<EXTERNAL-IP>'
        ]
    }
};
const client = await Client.newHazelcastClient(clientConfig);
import (
	"log"

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

func main() {
	config := hazelcast.Config{}
	cc := &config.Cluster
	cc.Network.SetAddresses("<EXTERNAL-IP>")
	ctx := context.TODO()
	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
	if err != nil {
		panic(err)
	}
}
import logging
import hazelcast

logging.basicConfig(level=logging.INFO)

client = hazelcast.HazelcastClient(
    cluster_members=["<EXTERNAL-IP>"],
    use_public_ip=True,
)

Now you can start the application.

  • Java

  • NodeJS

  • Go

  • Python

cd java
mvn package
java -jar target/*jar-with-dependencies*.jar
cd nodejs
npm install
npm start
cd go
go run main.go
cd python
pip install -r requirements.txt
python main.py

You should see the following output.

Successful connection!
Starting to fill the map with random entries.
Current map size: 2
Current map size: 3
Current map size: 4
Current map size: 5
Current map size: 6
Current map size: 7
Current map size: 8
Current map size: 9
Current map size: 10

Clean Up

To clean up the created resources remove the Hazelcast Custom Resource.

kubectl delete hazelcast my-hazelcast

See Also