A newer version of Hazelcast Operator is available.

View latest

Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

In this tutorial, you’ll deploy a Hazelcast cluster and an instance of Management Center, using Hazelcast Platform Operator for Kubernetes.

Before you Begin

You need a Kubernetes or Openshift cluster, and the kubectl or oc command-line tool must be configured to communicate with your cluster.

Step 1. Deploy Hazelcast Platform Operator

To deploy Hazelcast Platform Operator, apply the bundle-5.2.yaml file to your Kubernetes cluster:

  • Kubernetes

  • Openshift

kubectl apply -f https://repository.hazelcast.com/operator/bundle-5.2.yaml
oc apply -f https://repository.hazelcast.com/operator/bundle-5.2.yaml
If you always want to use the latest release, you can use the bundle-latest.yaml file.

At this point, the Hazelcast Platform Operator should be up and running. You can check it with the command below.

  • Kubernetes

  • Openshift

kubectl logs deployment.apps/hazelcast-platform-controller-manager
oc logs deployment.apps/hazelcast-platform-controller-manager
2021-07-14T09:03:40.713Z        INFO    setup   Watching namespace: default
2021-07-14T09:03:41.524Z        INFO    controller-runtime.metrics      metrics server is starting to listen    {"addr": ":8080"}
2021-07-14T09:03:41.524Z        INFO    setup   starting manager
2021-07-14T09:03:41.525Z        INFO    controller-runtime.manager      starting metrics server {"path": "/metrics"}

Optional: Customize the Namespace

By default, Hazelcast Operator is installed into the default namespace. If you want to change it, you can either replace all namespace: default parameters in bundle.yaml or use Kustomize to achieve it by creating the following kustomization.yaml file.

namespace: <your-namespace>
resources:
- bundle.yaml

Then, use Kustomize to apply bundle.yaml with the changed namespace.

  • Kubernetes

  • Openshift

kubectl apply -k .
oc apply -k .

If you deploy multiple Hazelcast Operators in different namespaces, you need a way to differentiate the name of each operator. For example, you can give each operator’s name a suffix by adding the nameSuffix field to the kustomization.yaml file:

namespace: <your-namespace>
resources:
- bundle.yaml
nameSuffix: <operator-suffix>

Note that you’ll need to add a parameter -n <your-namespace> to all further commands.

Step 2. Start the Hazelcast Cluster

After installing and running Hazelcast Platform Operator, you can create a Hazelcast cluster. First, create the Hazelcast custom resource file as hazelcast.yaml.

  • Open Source

  • Enterprise

  1. Create the Hazelcast custom resource file and name it hazelcast.yaml.

    apiVersion: hazelcast.com/v1alpha1
    kind: Hazelcast
    metadata:
      name: hazelcast-sample
    spec:
      clusterSize: 3
      repository: 'docker.io/hazelcast/hazelcast'
      version: '5.1.1-slim'
  2. Apply the custom resource to start the Hazelcast cluster.

    For Kubernetes
    kubectl apply -f hazelcast.yaml
    For Openshift
    oc apply -f hazelcast.yaml
  3. Verify that the cluster is up and running by checking the Hazelcast member logs.

    For Kubernetes
    kubectl logs pod/hazelcast-sample-0
    For Openshift
    oc logs pod/hazelcast-sample-0

You should see the following:

Members {size:3, ver:3} [
        Member [10.36.8.3]:5701 - ccf31703-de3b-4094-9faf-7b5d0dc145b2 this
        Member [10.36.7.2]:5701 - e75bd6e2-de4b-4360-8113-040773d858b7
        Member [10.36.6.2]:5701 - c3d105d2-0bca-4a66-8519-1cacffc05c98
]

Hazelcast Enterprise requires a license key. If you don’t have a license key, you can request one from the Hazelcast website.

  1. Create a Kubernetes secret to hold your license key.

    For Kubernetes
    kubectl create secret generic hazelcast-license-key --from-literal=license-key=<YOUR LICENSE KEY>
    For Openshift
    oc create secret generic hazelcast-license-key --from-literal=license-key=<YOUR LICENSE KEY>
  2. Create the Hazelcast custom resource file and name it hazelcast-enterprise.yaml.

    apiVersion: hazelcast.com/v1alpha1
    kind: Hazelcast
    metadata:
      name: hazelcast-sample
    spec:
      clusterSize: 3
      repository: 'docker.io/hazelcast/hazelcast-enterprise'
      version: '5.1.1-slim'
      licenseKeySecret: hazelcast-license-key
  3. Apply the custom resource to start the Hazelcast cluster.

    For Kubernetes
    kubectl apply -f hazelcast-enterprise.yaml
    For Openshift
    oc apply -f hazelcast-enterprise.yaml
  4. Verify that Hazelcast cluster is up and running by checking the Hazelcast member logs.

    For Kubernetes
    kubectl logs pod/hazelcast-sample-0
    For Openshift
    oc logs pod/hazelcast-sample-0

    You should see the following:

Members {size:3, ver:3} [
        Member [10.36.8.3]:5701 - ccf31703-de3b-4094-9faf-7b5d0dc145b2 this
        Member [10.36.7.2]:5701 - e75bd6e2-de4b-4360-8113-040773d858b7
        Member [10.36.6.2]:5701 - c3d105d2-0bca-4a66-8519-1cacffc05c98
]

Step 3. Check that the Hazelcast Cluster is Running

To check if a cluster is running, see the status field of the Hazelcast resource.

The status can be checked using the get hazelcast command.

  • Kubernetes

  • Openshift

kubectl get hazelcast
oc get hazelcast
NAME               STATUS    MEMBERS   EXTERNAL-ADDRESSES
hazelcast-sample   Running   3/3       35.240.99.152:5701

You can use the following command for the long format.

  • Kubernetes

  • Openshift

kubectl get hazelcast hazelcast-sample -o=yaml
oc get hazelcast hazelcast-sample -o=yaml
status:
  externalAddresses: 35.240.99.152:5701
  hazelcastClusterStatus:
    readyMembers: 3/3
  phase: Running

The phase field represents the current status of the cluster, and can contain any of the following values:

  • Running: The cluster is up and running.

  • Pending: The cluster is in the process of starting.

  • Failed: An error occurred while starting the cluster.

Any additional information such as validation errors will be provided in the message field.

The readyMembers field represents the number of Hazelcast members that are connected to the cluster.

Use the readyMembers field only for informational purposes. This field is not always accurate. Some members may have joined or left the cluster since this field was last updated.

Step 4. Start Management Center

You can monitor the Hazelcast cluster by starting Management Center.

  • Open Source

  • Enterprise

  1. Create the ManagementCenter custom resource file and name it management-center.yaml.

    apiVersion: hazelcast.com/v1alpha1
    kind: ManagementCenter
    metadata:
      name: managementcenter-sample
    spec:
      repository: 'hazelcast/management-center'
      version: '5.1.1'
      externalConnectivity:
        type: LoadBalancer
      hazelcastClusters:
        - address: hazelcast-sample
          name: dev
      persistence:
        enabled: true
        size: 10Gi
StatefulSet does not support updates to volumeClaimTemplates field, so persistence field should be set only at the creation of the custom resource. Any update to the persistence field will not affect the Management Center.
By default, Management Center data is persisted to the /data directory. If you want to use an existing PersistentVolumeClaim, set its name in the `.spec.persistence.existingVolumeClaimName`field in the Management Center custom resource.
hazelcastClusters field does not support deleting clusters from the custom resource. If you want to remove a cluster from the Management Center, you can do it from the Management Center UI.
  1. Apply it with the following command to start Management Center.

    For Kubernetes
    kubectl apply -f management-center.yaml
    For Openshift
    oc apply -f management-center.yaml
  2. After a moment, you can verify that Management Center is up and running by checking the Management Center logs.

    For Kubernetes
    kubectl logs pod/managementcenter-sample-0
    For Openshift
    oc logs pod/ -sample-0
2021-08-26 15:21:04,842 [ INFO] [MC-Client-dev.lifecycle-1] [c.h.w.s.MCClientManager]: MC Client connected to cluster dev.
2021-08-26 15:21:05,241 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.8.3]:5701 - ccf31703-de3b-4094-9faf-7b5d0dc145b2
2021-08-26 15:21:05,245 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.7.2]:5701 - e75bd6e2-de4b-4360-8113-040773d858b7
2021-08-26 15:21:05,251 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.6.2]:5701 - c3d105d2-0bca-4a66-8519-1cacffc05c98
2021-08-26 15:21:07,234 [ INFO] [main] [c.h.w.Launcher]: Hazelcast Management Center successfully started at http://localhost:8080/

To enable some features or dashboard at Management Center, you need a license key. If you don’t have a license key, you can request one from the Hazelcast website.

  1. Create a Kubernetes secret to hold your license key.

    For Kubernetes
    kubectl create secret generic hazelcast-license-key --from-literal=license-key=<YOUR LICENSE KEY>
    For Openshift
    oc create secret generic hazelcast-license-key --from-literal=license-key=<YOUR LICENSE KEY>
  2. Create the ManagementCenter custom resource file and name it management-center.yaml.

    apiVersion: hazelcast.com/v1alpha1
    kind: ManagementCenter
    metadata:
      name: managementcenter-sample
    spec:
      repository: 'hazelcast/management-center'
      version: '5.1.1'
      licenseKeySecret: hazelcast-license-key
      externalConnectivity:
        type: LoadBalancer
      hazelcastClusters:
        - address: hazelcast-sample
          name: dev
      persistence:
        enabled: true
        size: 10Gi
StatefulSet does not support updates to volumeClaimTemplates field, so persistence field should be set only at the creation of the custom resource. Any update to the persistence field will not affect the Management Center.
By default, Management Center data is persisted to the /data directory. If you want to use an existing PersistentVolumeClaim, set its name in the `.spec.persistence.existingVolumeClaimName`field in the Management Center custom resource.
hazelcastClusters field does not support deleting clusters from the custom resource. If you want to remove a cluster from the Management Center, you can do it from the Management Center UI.
  1. Apply it with the following command to start Management Center.

    For Kubernetes
    kubectl apply -f management-center.yaml
    For Openshift
    oc apply -f management-center.yaml
  2. After a moment, you can verify that Management Center is up and running by checking the Management Center logs.

    For Kubernetes
    kubectl logs pod/managementcenter-sample-0
    For Openshift
    oc logs pod/managementcenter-sample-0
2021-08-26 15:21:04,842 [ INFO] [MC-Client-dev.lifecycle-1] [c.h.w.s.MCClientManager]: MC Client connected to cluster dev.
2021-08-26 15:21:05,241 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.8.3]:5701 - ccf31703-de3b-4094-9faf-7b5d0dc145b2
2021-08-26 15:21:05,245 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.7.2]:5701 - e75bd6e2-de4b-4360-8113-040773d858b7
2021-08-26 15:21:05,251 [ INFO] [MC-Client-dev.event-1] [c.h.w.s.MCClientManager]: Started communication with member: Member [10.36.6.2]:5701 - c3d105d2-0bca-4a66-8519-1cacffc05c98
2021-08-26 15:21:07,234 [ INFO] [main] [c.h.w.Launcher]: Hazelcast Management Center successfully started at http://localhost:8080/

To access the Management Center dashboard, open the browser at address http://$MANCENTER_IP:8080.

  • Kubernetes

  • Openshift

MANCENTER_IP=$( kubectl get service managementcenter-sample -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
MANCENTER_IP=$( oc get service managementcenter-sample -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

If EXTERNAL-IP of the service is hostname, not IP, you can run command below:

  • Kubernetes

  • Openshift

MANCENTER_IP=$( kubectl get service managementcenter-sample -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
MANCENTER_IP=$( oc get service managementcenter-sample -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

Step 5. Clean up

You can run the commands below to remove the Hazelcast cluster and Management Center.

  • Kubernetes

  • Openshift

kubectl delete -f hazelcast.yaml
kubectl delete -f management-center.yaml
oc delete -f hazelcast.yaml
oc delete -f management-center.yaml

If you installed Hazelcast Enterprise, run the following commands to remove Hazelcast Enterprise cluster and Hazelcast License Key Secret.

  • Kubernetes

  • Openshift

kubectl delete -f hazelcast-enterprise.yaml
kubectl delete secret hazelcast-license-key
oc delete -f hazelcast-enterprise.yaml
oc delete secret hazelcast-license-key

Finally, run the command below to delete Hazelcast Platform Operator deployment.

  • Kubernetes

  • Openshift

kubectl delete -f https://repository.hazelcast.com/operator/bundle-5.2.yaml
oc delete -f https://repository.hazelcast.com/operator/bundle-5.2.yaml

Next Steps

Learn how to expose Hazelcast clusters outside Kubernetes so you can connect external clients to them.