Configure TLS with Hazelcast Platform Operator tutorial

Learn how to secure Hazelcast cluster with TLS and Hazelcast Kubernetes Operator.

Context

In this tutorial, you’ll do the following:

  • Create Kubernetes Secret with TLS certificate and key.

  • Deploy Hazelcast cluster with TLS (mTLS) encryption enforced between members.

  • Deploy Management Center to monitor your Hazelcast cluster.

  • Connect to your cluster using TLS to encrypt member to client network traffic.

Before you Begin

Before starting this tutorial, make sure that you meet the following prerequisites:

Step 1. Create Kubernetes Secret with TLS certificate and key

  1. Generate TLS certificate and key in PEM format using OpenSSL

    openssl req -x509 -sha256 -nodes -days 3650 -subj '/CN=example' -addext "subjectAltName=DNS:example" -newkey rsa:2048 -outform pem -keyout example.key -out example.crt -addext "extendedKeyUsage=serverAuth,clientAuth"

  2. Create Kubernetes Secret with TLS certificate and key

    kubectl create secret tls example --cert=example.crt --key=example.key
    In production setup it is advised to use tools like cert-manager to manage your certificates.

Step 2. Deploy Hazelcast cluster with TLS

  1. Create a secret with your Hazelcast Enterprise License.

    kubectl create secret generic hazelcast-license-key --from-literal=license-key=<hz-license-key>

  2. Create the Hazelcast cluster with TLS configured.

    kubectl apply -f - <<EOF
apiVersion: hazelcast.com/v1alpha1
kind: Hazelcast
metadata:
  name: hazelcast
spec:
  clusterSize: 3
  licenseKeySecretName: hazelcast-license-key
  tls:
    secretName: example
  exposeExternally:
    type: Smart
    discoveryServiceType: LoadBalancer
    memberAccess: LoadBalancer
EOF

  3. Run the following commands to check cluster status

    kubectl get hazelcast hazelcast
NAME        STATUS    MEMBERS
hazelcast   Running   3/3

  4. Run the following commands to fetch external addresses of the cluster:

    kubectl get hazelcastendpoint --selector="app.kubernetes.io/instance=hazelcast"
NAME            TYPE        ADDRESS
hazelcast       Discovery   35.184.21.18:5701
hazelcast-0     Member      35.188.131.33:5701
hazelcast-1     Member      34.122.242.55:5701
hazelcast-2     Member      35.194.44.37:5701
hazelcast-wan   WAN         35.184.21.18:5710

Step 3. Deploy Management Center

Enabling TLS for a Hazelcast cluster adds an essential layer of security to protect data during communication. When TLS is enabled, all clients, including the Management Center, must be configured with the appropriate TLS certificates to establish a secure connection with the Hazelcast cluster.

Apply the Management Center custom resource:

kubectl apply -f - <<EOF
apiVersion: hazelcast.com/v1alpha1
kind: ManagementCenter
metadata:
  name: managementcenter
spec:
  repository: 'hazelcast/management-center'
  externalConnectivity:
    type: LoadBalancer
  hazelcastClusters:
    - address: hazelcast
      name: dev
      tls:
        secretName: example
EOF

Step 4. Connect to Hazelcast cluster over TLS

  1. Clone the examples repository:

    git clone https://github.com/hazelcast-guides/hazelcast-platform-operator-tls.git
cd hazelcast-platform-operator-tls

    The sample code(excluding CLC) for this tutorial is in the docs/modules/ROOT/examples/ directory.

  2. Configure the Hazelcast client with the TLS certificate:

    • CLC

    • Java

    • NodeJS

    • Go

    • Python

    Before using CLC, it should be installed in your system. Check the installation instructions for CLC: Installing the Hazelcast CLC.

    Run the following command for adding the cluster config to the CLC.

    clc config add hz cluster.name=dev cluster.address=<EXTERNAL-IP> ssl.enabled=true ssl.server=example ssl.ca-path=<PATH/TO/example.crt>
    package com.hazelcast;

import com.hazelcast.client.HazelcastClient;
import com.hazelcast.client.config.ClientConfig;
import com.hazelcast.config.SSLConfig;
import com.hazelcast.core.HazelcastInstance;

import java.util.Properties;

public class example {
  public static void main(String[] args) throws Exception {
    ClientConfig config = new ClientConfig();
    config.getNetworkConfig().addAddress("<EXTERNAL-IP>");

    Properties clientSSLProps = new Properties();
    clientSSLProps.setProperty("trustStore", "example.jks");
    clientSSLProps.setProperty("trustStorePassword", "hazelcast");
    config.getNetworkConfig().setSSLConfig(new SSLConfig()
      .setEnabled(true)
      .setProperties(clientSSLProps));

    HazelcastInstance client = HazelcastClient.newHazelcastClient(config);
    System.out.println("Successful connection!");
  }
}
    'use strict';

const { Client } = require('hazelcast-client');

const clientConfig = {
  network: {
    clusterMembers: [
      '<EXTERNAL-IP>'
    ],
    ssl: {
      enabled: true,
      sslOptionsFactoryProperties: {
        caPath: 'example.crt',
        servername: 'example',
      }
    }
  }
};

(async () => {
  try {
    const client = await Client.newHazelcastClient(clientConfig);
    console.log('Successful connection!');
  } catch (err) {
    console.error('Error occurred:', err);
  }
})();
    package main

import (
	"context"
	"fmt"

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

func main() {
	var clusterConfig cluster.Config
	clusterConfig.Network.SetAddresses("<EXTERNAL-IP>")
	clusterConfig.Network.SSL.Enabled = true
	clusterConfig.Network.SSL.ServerName = "example"
	clusterConfig.Network.SSL.SetCAPath("example.crt")

	ctx := context.Background()
	config := hazelcast.Config{Cluster: clusterConfig}
	client, err := hazelcast.StartNewClientWithConfig(ctx, config)
	if err != nil {
		panic(err)
	}
	fmt.Println("Successful connection!", client)
}
    import logging

import hazelcast

logging.basicConfig(level=logging.INFO)

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

print("Successful connection!", flush=True)

  3. Build and run the Hazelcast client example:

    • CLC

    • Java

    • NodeJS

    • Go

    • Python

    clc -c hz map size
    cd java
mvn package
java -jar target/*.jar
    cd nodejs
npm install
npm start
    cd go
go run example.go
    cd python
pip install -r requirements.txt
python example.py

Step 5. Clean Up

To clean up the created resources remove the all Custom Resources and secrets:

kubectl delete $(kubectl get hazelcast,managementcenter -o name)
kubectl delete secret example

See Also