Skip to main content

Get Started with Embedded Hazelcast on Kubernetes

Deploy an application with embedded Hazelcast into a Kubernetes cluster.

Context​

Hazelcast instances from each application replica will all automatically discover themselves and form one consistent Hazelcast cluster. Thanks to Hazelcast Kubernetes discovery plugin, there is no static configuration needed.

Before you Begin​

Create an Application​

You can embed Hazelcast into any JVM-based application and use any web framework you want. As an sample for this tutorial, use the application from the Get Started with Hazelcast using Spring Boot tutorial. To download it, execute the following command.

git clone https://github.com/hazelcast-guides/hazelcast-embedded-springboot.git
tip

You can use any other JVM-based application framework, but please make sure your project includes a dependency to 'hazelcast:hazelcast:${hazelcast.version}' (or 'hazelcast:hazelcast-spring:${hazelcast.version}').

Use Hazelcast Kubernetes Configuration​

Hazelcast provides the dedicated Hazelcast Kubernetes plugin which allows to automatically form Hazelcast cluster in the Kubernetes environment. To enabled it, use the following Hazelcast configuration.

yaml
hazelcast:
  network:
    join:
      multicast:
        enabled: false
      kubernetes:
        enabled: true
        service-port: 5701

By default, Hazelcast looks for other members among all pods in its own namespace. The service-port setting makes it connect to them on Hazelcast's port, 5701. Without it, Hazelcast uses the first container port each pod declares, so pods that declare an application port, such as 8080, don't find each other.

Save this configuration as hazelcast.yaml in the directory that contains hazelcast-embedded-springboot. You'll add it to the Docker image in the next step, so the application uses it only when it runs in Kubernetes.

Now, you can build the project with the following command.

mvn package -f hazelcast-embedded-springboot/pom.xml

As an output, the JAR file with our application should be created at hazelcast-embedded-springboot/target/*.jar.

Containerize the Application​

To containerize the application, you need to have Docker installed. Then, save the following Dockerfile in the same directory as hazelcast.yaml.

dockerfile
FROM eclipse-temurin:25-jre
COPY hazelcast-embedded-springboot/target/*.jar app.jar
COPY hazelcast.yaml hazelcast.yaml
ENV SPRING_HAZELCAST_CONFIG=file:/hazelcast.yaml
ENTRYPOINT ["java","-jar","app.jar"]

The SPRING_HAZELCAST_CONFIG environment variable tells Spring Boot to use this file instead of the hazelcast.yaml packaged in the application, which uses multicast for running locally.

In order to build the Docker image, run the following command.

docker build -t hazelcast-embedded-kubernetes:0.1 .

Then, make the image available to your Kubernetes cluster:

  • Docker Desktop: Kubernetes in Docker Desktop can use the images you build with Docker, so there's nothing to do.
  • Minikube: minikube image load hazelcast-embedded-kubernetes:0.1
  • kind: kind load docker-image hazelcast-embedded-kubernetes:0.1

For other clusters, push the image to a registry that the cluster can pull from, and use that image name in the following steps. The image has a version tag rather than latest, so Kubernetes uses the image you built instead of trying to pull it from Docker Hub.

Configure RBAC​

Hazelcast Kubernetes discovery plugin makes calls to Kubernetes API to provide automatic member discovery. Therefore, it needs to have specific ClusterRole rules granted. You can apply the minimal RBAC configuration (for the default service account in the default namespace) with the following command.

kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast/master/kubernetes-rbac.yaml

Note that:

Deploy Application to Kubernetes​

Assuming you have a running Kubernetes cluster, you can run the following commands to deploy your application and scale it to 2 replicas.

kubectl create deployment my-app --image=hazelcast-embedded-kubernetes:0.1
kubectl scale deployment my-app --replicas=2

Now, if you look into created pods, you should see two replicas of your application.

$ kubectl get pods
NAME                      READY   STATUS    RESTARTS   AGE
my-app-86df8b785f-4x9pj   1/1     Running   0          81s
my-app-86df8b785f-h926d   1/1     Running   0          73s

In your application logs, you should see that embedded Hazelcast instances formed one cluster together.

$ kubectl logs pod/my-app-86df8b785f-4x9pj
...
Members {size:2, ver:2} [
        Member [10.24.1.10]:5701 - a7eb36b6-6d86-4d26-8eb6-47986e46d055 this
        Member [10.24.2.6]:5701 - 9994d6c6-d271-4ddd-9aa9-1ac4767c1a73
]

Test the Application​

To test that the application works correctly, you can create a Kubernetes service which load balances the traffic to one of the application replicas.

kubectl create service clusterip my-app --tcp=8080:8080

Then, to be able to make calls from your local machine, you can use port-forward.

kubectl port-forward service/my-app 8080:8080

Finally, you can make a REST calls to your application.

$ curl --data "key=key1&value=hazelcast" "localhost:8080/put"
{"value":"hazelcast"}
$ curl "localhost:8080/get?key=key1"
{"value":"hazelcast"}

Tear Down the Deployment​

To delete all Kubernetes resources you created, run the following command.

kubectl delete deployment/my-app service/my-app
kubectl delete -f https://raw.githubusercontent.com/hazelcast/hazelcast/master/kubernetes-rbac.yaml
Edit this page