Deploy a Cluster with the Hazelcast Platform Operator for Kubernetes

In this tutorial, you’ll deploy a Hazelcast cluster using Hazelcast Platform Operator for Kubernetes.

Prerequisites

A Kubernetes or OpenShift cluster
The kubectl or oc command-line tools, configured to communicate with your cluster
Helm

If you want to migrate from the Hazelcast Helm Chart, please follow the guidance in Migrating from Helm document.

Step 1. Deploy Hazelcast Platform Operator

From release 5.6.0 onwards, you can use a Helm chart to install the Hazelcast Platform Operator.

Add the Hazelcast Helm Charts repository to your Helm repository list by running the following command:
```
helm repo add hazelcast https://hazelcast-charts.s3.amazonaws.com/
helm repo update
```

You can either deploy the Hazelcast Platform Operator at the same time as CRDs or separately.

Since CRDs are global resources, they may need to be installed by an administrator.

Cluster Wide Installation
Restricted Installation

Run the following command to deploy the Operator and the CRDs together. By default, the Hazelcast Platform Operator watches all namespaces. Use the watchedNamespaces variable to update this configuration.

helm install operator hazelcast/hazelcast-platform-operator --version=5.15.0-snapshot \
    --set=installCRDs=true

Run the following commands to deploy the Operator and the CRDs separately. An administrator may need to do this.

helm install operator-crds hazelcast/hazelcast-platform-operator-crds --version=5.15.0-snapshot

After installing CRDs, install the Operator by running the following command. This operation requires only namespace-scoped permissions for hz-system, ns-1 and ns-2 namespaces which should already exist.

helm install operator hazelcast/hazelcast-platform-operator --version=5.15.0-snapshot -n hz-system \
    --set=createClusterScopedResources=false \(1)
    --set=webhook.enabled=false \(2)
    --set=enableHazelcastNodeDiscovery=false \(3)
    --set=installCRDs=false \
    --set=watchedNamespaces="{ns-1, ns-2}"

1	Disabling `createClusterScopedResources` means that the management of resources by Operator is constrained to specified namespaces. This enhances both security and compliance.
2	Disabling `webhook.enabled` means that webhooks cannot be used. This is needed as the cluster-wide permissions required for webhooks conflict with our restrictions on cluster-scoped resource creation.
3	Disabling `enableHazelcastNodeDiscovery` means that Operator does not automatically discover nodes across all namespaces. This limits the use of `NODE_AWARE` in `highAvailabilityMode` and of `NodePort` in `discoveryServiceType`, both of which depend on broader node discovery.

You can view all configuration options by running the following command: helm show values hazelcast/hazelcast-platform-operator

Monitor the operator logs. 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/operator-hazelcast-platform-operator -n hz-system
oc logs deployment.apps/operator-hazelcast-platform-operator -n hz-system

Step 2. Start the Hazelcast Cluster

After installing and running the Hazelcast Platform Operator, you can create a Hazelcast cluster.

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

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>

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.5.2-slim'
  licenseKeySecretName: hazelcast-license-key

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
```
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
hazelcast-sample   Running   3/3

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:
  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. Clean up

Run the following commands to remove Hazelcast 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 the Hazelcast Platform Operator deployment.

helm uninstall operator

If you installed the CRDs separately from the operator, you need to remove them by running the following command:

helm uninstall operator-crds

Next Steps

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