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

Docker (Docker for Desktop is good enough)
Kubernetes cluster (Docker for Desktop or Minikube is good enough)
Git
JDK 1.8+
Apache Maven 3.2+

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

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.

hazelcast:
  network:
    join:
      multicast:
        enabled: false
      kubernetes:
        enabled: true

To include this file inside your Spring Boot project, copy it into hazelcast-embedded-springboot/src/resources/.

cp hazelcast.yaml hazelcast-embedded-springboot/src/main/resources/

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, you can use the following Dockerfile.

FROM openjdk:8-jre-alpine
COPY hazelcast-embedded-springboot/target/*.jar app.jar
ENTRYPOINT ["java","-jar","app.jar"]

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

docker build -t hazelcastguides/hazelcast-embedded-kubernetes .

If you build the image by yourself, then you need to use your Docker Hub account instead of hazelcastguides. Then, you can push the image into your Docker Hub registry with the following command.

docker push hazelcastguides/hazelcast-embedded-kubernetes

If you want to use your image in the following steps, please also make sure your Docker Hub registry is public. However, for the purpose of this guide, you can use the already built hazelcastguides/hazelcast-embedded-kubernetes Docker image.

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:

If you use service account other than default or namespace other than default, you need to modify https://raw.githubusercontent.com/hazelcast/hazelcast/master/kubernetes-rbac.yaml
If your Kubernetes cluster does not use RBAC, you can skip the whole "Configure RBAC" step

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=hazelcastguides/hazelcast-embedded-kubernetes
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